Pressure-testing Ota on athena-api: Bundler hydration, workflow truth, and governed service launch

athena-api forced Ota to grow up in two places at once:

• Ruby and Bundler had to become a real first-class dependency hydration surface instead of a repo-local special case.
• long-running Rails service tasks had to stop hiding behind opaque shell run strings once Ota already had a stronger launch.kind: command surface.

Later, once the matrix moved from source-install proof to released v1.6.20 proof, the same repo exposed a second governance problem: the hosted installer contract for GitHub Actions was still too easy for workflow authors to misuse on Windows.

That combination made this repo unusually useful.

It was not just a Ruby pressure test. It was also a governance test.

If Ota could parse a Rails contract but still make authors express common service starters as shell text, the product surface was still weaker than it should be.

This repo exposed five meaningful weaknesses.

1. Bundler dependency hydration was missing from the shipped Ota surface

The contract wanted to model repo-local gem hydration directly:

prepare:  kind: dependency_hydration  medium: package_dependencies  source:    kind: bundler    cwd: .    path: vendor/bundle

That is repo truth for a Rails app.

At the start of the pressure cycle, the CI-built Ota binary rejected that shape during ota validate because bundler was not yet recognized as a valid dependency hydration source.

That was an Ota gap, not an athena-api mistake.

2. Windows shell startup broke Bundler execution truth

Once Bundler hydration existed, Windows exposed another engine defect.

Ota was launching native POSIX-like commands through bash -lc, which reset execution into $HOME before running the command. That meant Bundler lost the repo Gemfile and the contract failed for the wrong reason.

That bug only became obvious because the matrix included a Windows lane.

3. workflow-scoped service truth was weaker than it looked

The repo also exposed an execution-boundary problem.

A selected workflow should only inherit the services it actually declares. Ota was still allowing a bounded workflow like verify-static to inherit unrelated repo-global required services during ota up.

That is exactly the sort of hidden overreach that makes a contract look cleaner than the runtime truth it actually enforces.

4. the docs and examples were under-teaching launch.kind: command

The contract could already model long-running service launch structurally, but the public guidance was still too permissive about raw run for common service starters.

That is a docs and governance weakness, not just an authoring preference issue.

If the stronger surface already exists, pressure testing should push authors and docs toward it.

5. the hosted installer contract for GitHub Actions was too weak

Once the pressure repos moved away from source-install proof and onto released Ota binaries, athena-api exposed another product-level weakness.

The workflow used the correct installer command, but it still had to guess where ota would land on Windows for later steps. That guess was wrong.

The immediate repo bug was a bad GITHUB_PATH assumption. The deeper Ota problem was that the hosted installer contract was not machine-usable enough for CI consumers. If a workflow author has to infer the post-install binary location manually, that surface is still too weak.

athena-api led to several real Ota fixes.

Bundler dependency hydration support

Ota grew a real Bundler hydration lane for:

• schema parsing
• validation
• execution
• rendered output

That moved Bundler from repo-local workaround territory into the shipped task preparation surface.

Windows Bash cwd behavior

Ota's Windows native command path was tightened so Bash-backed command execution does not silently reset into the wrong working directory before Bundler runs.

That fix belongs in Ota because repo contracts should not need to compensate for CLI shell drift.

Selected-workflow service scoping

Ota was fixed so a selected workflow only carries the services it explicitly declares instead of inheriting unrelated repo-global required services during bounded execution.

That made verify-static truthful instead of accidentally relying on broader repo state.

Governance and public reference hardening

This repo also triggered a product-level docs correction:

• launch.kind: command is now explicitly governed as the preferred shape for long-running service processes
• runtime / surfaces or listeners are now explicitly framed as exposure and readiness truth
• run is now framed more clearly as the finite shell-task path

That update landed across Ota core docs, examples, the public site, and a dedicated task-launch reference page.

GitHub Actions installer contract hardening

This repo also helped force a clearer installer boundary.

Ota's hosted installers now export the resolved ota bin directory to GITHUB_PATH automatically when they run inside GitHub Actions. That means CI authors no longer need to guess between paths such as ~/.local/bin and %LOCALAPPDATA%\\ota\\bin just to make later workflow steps find ota.

That is not a parser or runtime-engine fix. It is still an Ota-owned platform fix because installation governance is part of the public operational contract.

The final contract is stronger because it now uses the stronger Ota surfaces directly instead of just being syntactically valid.

The most important change is that the long-running Rails service tasks now use launch.kind: command.

dev:  context: ruby-host  description: Start the Rails API server  launch:    kind: command    exe: bundle    args:      - exec      - rails      - server      - -b      - 0.0.0.0      - -p      - "3000"  depends_on:    - db:prepare  requires_services:    - postgres  requirements:    toolchains:      - ruby  effects:    writes:      - log      - tmp      - storage    external_state:      - postgres  runtime:    kind: service    surfaces:      api:        project:          host:            primary: true

The worker follows the same pattern:

worker:  context: ruby-host  launch:    kind: command    exe: bundle    args:      - exec      - rails      - solid_queue:start

That matters because the contract now separates two different truths cleanly:

• launch starts the process
• runtime describes what service surface becomes reachable

That is stronger than treating Rails server startup as just another shell string.

The verification entrypoints also got stronger:

verify:  aggregate:    tasks:      - lint      - security:brakeman      - security:audit      - test

That replaces the old fake run: "true" wrapper with a first-class aggregate task body.

The current green matrix run is honest about scope.

At the time of writing, the latest cleared run for this branch is #27463819430, on June 13, 2026.

That matters because the branch was not only validated against the earlier source-pressure cycle. It also survived the later move to released v1.6.20 plus the Windows installer-contract correction.

It proves:

• ubuntu-full
• macos-full
• ubuntu-container
• windows-static

That last lane matters.

Windows is not being presented as full Rails plus PostgreSQL runtime proof. It is intentionally a static verification lane. The matrix is not pretending to prove a Windows runtime surface it does not actually provision.

That is the right trade-off for this repo:

• full runtime proof where the signal is strong
• bounded static verification where the platform lane is still valuable but full local database-backed runtime proof would mostly measure installer drift instead of Ota

It also now proves one more governance point cleanly: released-binary matrix coverage is part of the truth. A contract that only goes green when Ota is built from source inside the workflow is weaker than a contract that still holds under the public install surface users and CI will actually consume.

athena-api mattered because it pushed on a very common repo shape:

• Rails app
• Bundler-owned dependency lane
• local PostgreSQL dependency
• one long-running API server
• one long-running worker

That is not an exotic contract.

It is a common application shape that Ota should model cleanly.

Common Rails service tasks should not need opaque shell launch when Ota already has a stronger surface.

And Bundler should not be a second-class dependency lane when Ruby repos are part of the real readiness world Ota claims to support.

That is what made this repo worth pressure-testing. It did not just help one contract go green. It forced the product to get stronger where the current surface was still too weak.

• Contract: athena-api ota.yaml
• Matrix workflow: test-ota-contract-matrix.yml
• Green matrix run: #27463819430

athena-api reinforced a product rule that should stay strict:

if Ota already has a stronger first-class surface, pressure testing should not normalize the weaker shell-shaped authoring path.

The right response is to harden the product, then teach the stronger path clearly.