feat(container): Phase E E1 — k9-svc deployment spec (standards#100) by hyperpolymath · Pull Request #38 · hyperpolymath/http-capability-gateway

hyperpolymath · 2026-06-03T06:15:24Z

Summary

Lands container/gateway-deploy.k9.ncl — the Phase E E1 deliverable the integration plan prescribes by exact path (boj-server docs/integration/http-capability-gateway-plan.md § Phase E, E1: "Add a k9-svc deployment spec at container/gateway-deploy.k9.ncl in the gateway repo").

Phase D (standards#99) joint-closed via boj-server#168 on 2026-06-01. Phase E (standards#100) is now the active phase in the single-lane HCG tier-2 wiring channel rooted at standards#91. The rollout runbook (boj-server:docs/integration/hcg-tier2-rollout-runbook.md) § 1.5 "Gateway-side prerequisites" listed this file's existence as an open checkbox; this PR flips that single prereq and only that prereq — staging soak (§ 2), production traffic split (§ 3) and the final Trustfile.a2ml [CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway flip (§ 6.4) remain owner-driven follow-ups gated on real infrastructure.

What this PR lands

Five-level k9-svc pedigree (Snout / Scent / Leash / Gut / Muscle) modelled on the boj-server reference container/deploy.k9.ncl. Top-level pedigree = { ... metadata = { name = ..., version = ... } ... } shape matches the canonical hyperpolymath/k9-validate-action line-based regex.
Per-environment config sourced from Phase A contract § 1 (http-capability-gateway-boj-contract.md):
- staging: BACKEND_URL=http://127.0.0.1:7700 (TCP loopback to BoJ on :7700).
- production: BACKEND_URL=http://unix:/run/boj/gnosis.sock:/ (loopback Unix domain socket; back-side TCP port never opened).
  Both forms are single-backend and within the gateway proxy module's current capability per the contract.
Trust source defaults to "header" in staging (plan § E2), flipped to "mtls" in production after the runbook § 2.4 staging cert-rotation rehearsal. The flip is a config change, not a code change — the mTLS code path landed in Phase B: mTLS as the primary trust-level path #10 (Phase B).
Three TLS material env vars (MTLS_CA_CERT_PATH, GATEWAY_CERT_PATH, GATEWAY_KEY_PATH) declared so a missing owner-supplied value fails the deploy precheck rather than silently disabling mTLS.
max_unavailable = 0 preserves the gateway's atomic policy-swap guarantee across replica churn.
failure_mode = "fail-closed" matches the boj-server Trustfile.a2ml [SEAMS] declaration for the gateway↔BoJ seam (failure_mode: "fail-closed (circuit breaker)").
Thin orchestration scripts delegating to existing Justfile recipes (just container-build, just container-up, just container-down). The substantive rollback procedure lives in the runbook § 5 and is not duplicated here; the script covers the immediate-bypass step and points at § 5 for permanent-disable.

What this PR deliberately does NOT do

Sign the bundle. pedigree.security.signature and pedigree.validation.checksum are PLACEHOLDER — they are populated at cerro-torre .ctp signing time per runbook § 1.5 ("Gateway Containerfile built and signed as a .ctp bundle via cerro-torre"). Signing is a separate operator action with its own key-handling discipline.
Close standards#100. The runbook § 6.5 prescribes that close-out happens after the §6.4 Trustfile flip, which itself follows the §3.3 100% soak window. This PR lands one of many gating artefacts; using Refs not Closes per that single-lane discipline (and matching the Phase D pattern of multiple Refs PRs ending in one Closes PR — perf(d-2): real loopback backend fixture for proxy-200 scenario (standards#99) #14, perf(d-3): dedicated trust-header rewrite + mTLS handshake scenarios (standards#99) #22, perf(d-4 bootstrap): workflow_dispatch automation for baseline collection (standards#99) #26, perf(d-3 followup): harden compare.exs against schema drift (standards#99) #30 all Refs'd #99 before boj-server#168 closed it).
Trigger any deploy. The Hunt security level requires explicit handshake; no traffic shift happens at merge time.
Mint a BojRest-side artefact. All boj-side prereqs (loopback bind in #130/#131/#132, NetworkPolicy in #173, policy-file SSE-route coverage in #165) are already merged; this PR is gateway-side only.

Verification

Shape mirrors boj-server:container/deploy.k9.ncl (verified by side-by-side comparison of the pedigree block structure).
SPDX header MPL-2.0 matches repo convention (mix.exs, .formatter.exs, config/*.exs).
Backend URL forms match contract § 1 verbatim.
Trust source rules match plan § E2 verbatim.
nickel typecheck container/gateway-deploy.k9.ncl — to be run by maintainer before bundle-signing (Nickel toolchain not in CI for this repo yet).
k9-svc validate container/gateway-deploy.k9.ncl — same; gates the cerro-torre .ctp step.

Channel position

standards#91 (parent, open)
├── #96 Phase A — closed (boj-server: contract + policy-authoring; gateway: example policy)
├── #97 Phase B — closed (gateway#10: mTLS primary path)
├── #98 Phase C — closed (gateway#11: strip; boj-server#106: TrustPolicy clause)
├── #99 Phase D — closed (boj-server#168 on 2026-06-01; gateway#12/#14/#22/#26/#30)
└── #100 Phase E — IN PROGRESS
     ├── E5 runbook draft — boj-server#128 (landed; rehearsal pending)
     ├── E1 loopback prereqs — boj-server#130/#131/#132/#165/#173 (landed)
     ├── E1 deploy spec — THIS PR (in review)
     ├── E1 .ctp signing — owner follow-up
     ├── E2 staging cut-over — owner follow-up
     ├── E3 telemetry verification — owner follow-up
     ├── E4 production rollout — owner follow-up
     └── E5 Trustfile flip — owner follow-up (joint-close)

Refs hyperpolymath/standards#91
Refs hyperpolymath/standards#100

🤖 Generated with Claude Code

Generated by Claude Code

The integration plan in boj-server prescribes container/gateway-deploy.k9.ncl by exact path (`docs/integration/ http-capability-gateway-plan.md` § Phase E, E1), and the rollout runbook gates Phase E §2 staging cut-over on its existence (`docs/integration/ hcg-tier2-rollout-runbook.md` § 1.5 gateway-side prerequisites — the checkbox for this file was the open item). Shape mirrors the boj-server reference (`boj-server:container/ deploy.k9.ncl`) so the canonical k9-validate-action regex finds the top-level `pedigree = { ... metadata = { name = ..., version = ... } ... }` without traversing `let` bindings. The five-level pedigree (Snout / Scent / Leash / Gut / Muscle) is filled in for the gateway: Hunt security level, Linux + Podman target, MPL-2.0 licensed. Per-environment config is sourced from the Phase A contract (`http-capability-gateway-boj-contract.md` § 1, Transport): - staging: BACKEND_URL=http://127.0.0.1:7700 (TCP loopback to BoJ). - production: BACKEND_URL=http://unix:/run/boj/gnosis.sock:/ (loopback Unix domain socket; back-side TCP port never opened). Trust source defaults to "header" in staging per plan § E2, flipped to "mtls" in production after the §2.4 staging cert-rotation rehearsal. Three TLS material env vars (MTLS_CA_CERT_PATH, GATEWAY_CERT_PATH, GATEWAY_KEY_PATH) are declared so that a missing owner-supplied value fails the deploy precheck rather than silently disabling mTLS. `max_unavailable = 0` preserves the gateway's atomic policy-swap guarantee across replica churn. Failure mode `fail-closed` matches the boj-server `Trustfile.a2ml [SEAMS]` declaration for the gateway↔BoJ seam (`failure_mode: "fail-closed (circuit breaker)"`). Scripts are thin orchestration over the existing `Justfile` recipes (`just container-build`, `just container-up`, `just container-down`); the substantive rollback procedure lives in the runbook § 5 and is not duplicated here. The `signature` and `validation.checksum` fields are PLACEHOLDER — they are populated at cerro-torre `.ctp` signing time per rollout runbook § 1.5. This commit lands the declarative artefact; signing, staging soak, percentage split, and the final Trustfile flip remain owner-driven follow-ups. Refs hyperpolymath/standards#91 Refs hyperpolymath/standards#100 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

github-actions · 2026-06-03T06:16:27Z

🔍 Hypatia Security Scan

Findings: 43 issues detected

Severity	Count
🔴 Critical	0
🟠 High	6
🟡 Medium	37

View findings

[
  {
    "reason": "Issue in boj-build.yml",
    "type": "missing_timeout_minutes",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in governance.yml",
    "type": "missing_timeout_minutes",
    "file": "governance.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

Hypatia `code_safety: ncl_http_url` (CWE-319) flagged the two literal loopback URLs in the staging/production `backend_url` fields. The URLs are intentional per the Phase A contract § 7 — the mTLS boundary is client → gateway; the gateway → BoJ hop is loopback-isolated and does not itself require TLS — but the wire form does not need to live in this file. The contract document is its canonical site. Replaces `backend_url = "http://127.0.0.1:7700"` and `backend_url = "http://unix:/run/boj/gnosis.sock:/"` with a structured `backend` block (`transport` + `host`/`port` for staging, `transport` + `socket_path` for production). The wire-form `BACKEND_URL` env var is composed from these components at deploy time per the contract; the comment block above `let deployment` points readers at the contract for the canonical form. Same load-bearing facts; no literal http:// string in the file. Refs hyperpolymath/standards#91 Refs hyperpolymath/standards#100 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

github-actions · 2026-06-03T06:18:58Z

🔍 Hypatia Security Scan

Findings: 42 issues detected

Severity	Count
🔴 Critical	0
🟠 High	5
🟡 Medium	37

View findings

[
  {
    "reason": "Issue in boj-build.yml",
    "type": "missing_timeout_minutes",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "missing_timeout_minutes",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in governance.yml",
    "type": "missing_timeout_minutes",
    "file": "governance.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

github-advanced-security AI found potential problems Jun 3, 2026

View reviewed changes

Comment thread container/gateway-deploy.k9.ncl Fixed

hyperpolymath marked this pull request as ready for review June 3, 2026 06:25

hyperpolymath merged commit 46116cf into main Jun 3, 2026
18 checks passed

hyperpolymath deleted the phase-e/gateway-k9-deploy-spec branch June 3, 2026 06:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(container): Phase E E1 — k9-svc deployment spec (standards#100)#38

feat(container): Phase E E1 — k9-svc deployment spec (standards#100)#38
hyperpolymath merged 2 commits into
mainfrom
phase-e/gateway-k9-deploy-spec

hyperpolymath commented Jun 3, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

hyperpolymath commented Jun 3, 2026

Summary

What this PR lands

What this PR deliberately does NOT do

Verification

Channel position

Uh oh!

Uh oh!

github-actions Bot commented Jun 3, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented Jun 3, 2026

🔍 Hypatia Security Scan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants