This is the multi-page printable view of this section. Click here to print.
Specifications
1 - Architecture diagram
1.1 - architecture-diagram Specification
Purpose
Describe the maintained architecture diagram owned by
infra/dev. The diagram replaced the T3code page of the
former central Drawio document. Infrastructure diagrams now live with their
owning projects, with ownerless archived diagrams under infra/archive.
The diagram describes checked-in configuration; it is not a live inventory or
health check.
Requirements
Requirement: Owner-local Mermaid diagram source
The project SHALL keep its architecture diagram as Mermaid source at
t3code-architecture.mmd and SHALL render it through the repository’s
mermaid_svg rule at //infra/dev:rendered. The project
SHALL NOT commit a rendered SVG: //infra/dev:docs_assets
SHALL take its srcs from :rendered so the documentation site publishes the
build output, and the README SHALL reference that published path. The diagram
SHALL use the shared //tools/mermaid:theme.json appearance rather than a
package-local copy.
Scenario: Publish the diagram
- WHEN the documentation site is built
- THEN
:docs_assetspackages the SVG produced by:rendered - AND the README image reference resolves to that packaged file
- AND no rendered SVG is tracked in the source tree
Scenario: Render without host or network inputs
- WHEN the render action produces the SVG
- THEN it uses the repository’s pinned Mermaid, headless Chrome, and font inputs
- AND it loads no stylesheet, script, or font from a CDN
- AND the document embeds the pinned handwriting face, so a viewer that loads no webfont still lays the labels out at their measured widths
Requirement: Diagram content reflects the deployed topology
The diagram SHALL group the remote actor and the shared Ingress in an
Internet cluster, and SHALL show the remote actor reaching Ingress over
HTTPS with mTLS. It SHALL nest the host-bot cluster inside the local
infrastructure cluster, so the local actor, Vault, and the host’s services
sit inside dc1.alwaldend.com rather than beside it, and the two nested cluster
titles SHALL carry the dc1.alwaldend.com and
dev1.dev.alwaldend.com names respectively. It SHALL group
Traefik, T3 Code, and Codex in the host-bot cluster, SHALL show the local
actor reaching Traefik directly over HTTPS, Ingress forwarding to Traefik
over Wireguard, and Traefik obtaining ACME certificates from Vault. It
SHALL show T3 Code reaching GitHub for source and Codex reaching OpenAI and
OpenRouter for inference, with those providers in a second Internet cluster
because they are off-host. Both actors SHALL be labelled Actor. External
service nodes SHALL carry their own hostnames.
Sources: diagram source and project documentation.
Scenario: Consult the host-bot architecture
- WHEN a reader opens the architecture section of the project README
- THEN it displays the maintained diagram showing the ingress path, the in-host services, and the two external service dependencies
Requirement: Legible diagram layout
The diagram SHALL keep node labels short by naming each host once, in the cluster title that owns it, and SHALL NOT restate a hostname in both a cluster title and the nodes it contains. Node labels SHALL NOT wrap mid-token. The diagram SHALL keep subgraph titles clear of node outlines and edges: Mermaid centers a cluster title on the cluster’s top border, so a title that wraps extends into the cluster’s node area. The diagram source SHALL describe topology only and SHALL let the shared theme own appearance and spacing; a per-diagram directive is warranted only for a specific geometry need the theme cannot express.
Actors SHALL render as an ordinary rounded node carrying the shared theme’s
hand-drawn stick figure beside the label, rather than as a bare glyph, a pill
outline, or a Mermaid person shape. Mermaid’s person shape draws the head
over the body box, so it is not used.
Sources: diagram source and theme.
Scenario: Render the maintained layout
- WHEN the renderer draws the diagram
- THEN every node outline is clear of headings, edges, and other nodes
- AND no label is truncated or broken inside a hostname
Requirement: Appearance is owned by the shared theme
Diagram appearance SHALL come from //tools/mermaid:theme.json rather than
package-local copies or per-diagram appearance overrides, so node rounding and
edge-label plates are consistent across every rendered diagram. The theme SHALL
keep shapes semantic, so a rounded bracket node renders rounded while a square
bracket node stays square; rounding SHALL NOT be forced on every node. The
theme SHALL box edge labels by styling the label text, because Mermaid emits an
empty label plate for unlabelled edges and styling that plate directly would
draw a stray box.
Source: theme.
Scenario: Render another diagram with the theme
- WHEN any diagram renders through
mermaid_svgor themmdctarget - THEN a rounded node renders rounded and a square node stays square
- AND its edge labels use bordered plates
Scenario: Read an edge annotation
- WHEN the renderer draws an edge that carries a label
- THEN the label renders on a bordered plate rather than directly on the edge line
- AND an edge without a label draws no plate
2 - Bazel resource scheduling
2.1 - bazel-resource-scheduling Specification
Purpose
Reduce resource contention from independent Bazel builds on host-bot through conservative per-invocation scheduling defaults.
Requirements
Requirement: Reduced per-invocation scheduling defaults
The managed user Bazel configuration SHALL set four concurrent jobs and a local CPU scheduling budget of HOST_CPUS*0.25 for builds and tests. These defaults SHALL NOT be described as an aggregate host-wide resource cap.
Scenario: Build or test reads the managed defaults
- WHEN a new Bazel build or test invocation loads the managed user configuration without overriding its resource settings
- THEN it receives
--jobs=4and--local_resources=cpu=HOST_CPUS*0.25
Scenario: Independent workspaces build concurrently
- WHEN separate Bazel servers build in multiple workspaces
- THEN each receives its own scheduling budget, without sharing an aggregate limit
3 - Infra forgejo runner
3.1 - Secure runner infrastructure specification
Purpose
Describe the host-only secure1 baseline under infra/dev. The checked-in source does not install or register an Actions worker and does not establish live state.
Requirements
Requirement: No legacy Proxmox allocation
The owner SHALL NOT declare runner1/VM 1200, its old DNS entry or its inventory entry. Secure1 SHALL retain its host-only configuration. Its DNS SHALL belong to the common dns root without a Proxmox provider or login.
Scenario: Inspect runner allocation
- WHEN the current source is inspected
- THEN no legacy Proxmox allocation or separate tf_setup root remains
- AND secure1 DNS and host configuration remain available
Requirement: Host-only deployment baseline
The secure1 play SHALL apply only the shared host role to the secure1 inventory group. It SHALL NOT require runner registration credentials, an Actions instance URL or a runner disk setting.
Scenario: Determine the playbook effect
- WHEN the current playbook is inspected
- THEN only the shared host role is enabled
- AND runner installation and registration remain outside this baseline
4 - Openspec cli
4.1 - openspec-cli Specification
Purpose
Keep Host Bot’s user-facing OpenSpec CLI installation reproducible through its checked-in Ansible deployment.
Requirements
Requirement: Managed OpenSpec CLI installation
Host Bot’s Ansible deployment SHALL install @fission-ai/openspec at an exact
inventory-configured version under the managed user’s ~/.local prefix, with
Node.js and npm provisioned through the existing host package backend.
Repeated deployment with the same version SHALL preserve the installed version.
Scenario: Provision the CLI
- WHEN the Host Bot deployment runs with OpenSpec absent
- THEN it installs the configured version and exposes
~/.local/bin/openspecto the managed user
Scenario: Repeat the deployment
- WHEN the configured OpenSpec version is already installed
- THEN the npm task leaves the package unchanged
5 - Owned dns
5.1 - Development DNS specification
Purpose
Define one DNS deployment for both development hosts and dev1’s services.
Requirements
Requirement: One owner-local DNS root
The dns root SHALL consume the complete canonical dnsconfig.json through the shared DNS module, preserving all declared views. It SHALL use src_infra_dev and the alwaldend.com/vault1/approles/src_infra_dev/tf_backend/dns backend. There SHALL be no separate runner DNS root or record filter.
Scenario: Evaluate the declaration
- WHEN the DNS root is evaluated
- THEN secure1, dev1 and dev1’s service records belong to the same root
- AND provider credentials are injected through the shared owner identity
Requirement: Explicit ownership handoff
The owner SHALL document the pending transfer from both legacy states and preserve legacy access until separately authorized reconciliation is complete. Adoption SHALL bind existing DNS records without destructive recreation or concurrent ownership. Unrelated legacy resources SHALL NOT be transferred or destroyed by implication. After adoption, unchanged declarations SHALL produce a no-change plan, and temporary import configuration SHALL be removed.
Scenario: Review source before adoption
- WHEN a maintainer inspects the merged root
- THEN the legacy backend locations and logical-key changes are documented
- AND source validation makes no claim of live ownership or deployment
Requirement: Offline source checks
The package SHALL expose a format check and package both DNS provider binaries, the canonical declaration and shared module without live authentication.
Scenario: Validate source
- WHEN offline checks run
- THEN they validate packaged source without contacting Vault or DNS providers
6 - Power profile
6.1 - power-profile Specification
Purpose
Keep the host’s selected power profile reproducible through its owning Ansible configuration while retaining an explicit desired profile.
Requirements
Requirement: Managed host power profile
The host’s Ansible configuration SHALL declare balanced as its desired
Tuned profile. Deployment SHALL enable and start the existing Tuned service
and persist the declared profile with manual selection. Deployment SHALL
avoid reselecting an already-correct profile in manual mode and SHALL
report unexpected profile-query failures.
Scenario: Selected profile differs
- WHEN the active profile differs from the declared profile
- THEN deployment selects and persists the declared profile
Scenario: Automatic selection is enabled
- WHEN the active profile matches but selection is automatic
- THEN deployment persists the declared profile with manual selection
Scenario: No profile is active
- WHEN Tuned reports that no profile is active
- THEN deployment selects the declared profile instead of failing on that expected query result
Scenario: Desired state already matches
- WHEN the active profile matches and selection is manual
- THEN deployment does not repeat the profile-selection command
Scenario: Query fails unexpectedly
- WHEN querying the active profile or selection mode fails unexpectedly
- THEN deployment reports the failure instead of concealing it