feat(cost): project OpenCost namespace allocations

[gnanirahulnutakki]

Summary

• add a pure, bounded OpenCost v1.120.2 namespace-allocation projector
• emit deterministic FactCost / LensTelemetry facts attached to exact cluster and Kubernetes namespace identity
• validate canonical five-decimal USD components and OpenCost's total formula with exact rational arithmetic
• fail the whole response on ambiguous query, window, identity, warning, JSON, decimal, or total state
• document the USD-only boundary, privacy contract, costs, alternatives, and incomplete live-reader status

Closes #282. Progresses #31 without claiming F13.1 or E13 complete.

Contract and non-goals

The trusted caller supplies one already-authorized /allocation response for an explicit UTC window, aggregate=namespace, step=window, and disabled filter, accumulation, idle, sharing, proportional-asset, and aggregated-metadata options. OpenCost's allocation JSON does not prove currency, so this first protocol requires an explicit USD assertion and rejects every other unit.

This PR adds no HTTP client, discovery, credentials, persistence, billing, metering, recommendations, optimization, mutation, Hub/team rollup, currency conversion, freshness objective, GPU utilization/efficiency, DCGM, or MIG claim. The current CLI and Hub do not fetch or display these facts.

Security, reliability, and cost

• response size, allocation count, fact payload, identity text, JSON depth, window, clock skew, decimal length/scale, and amount magnitude are bounded
• duplicate keys, mixed-case aliases, invalid UTF-8, trailing data, non-success/warned/multi-set responses, synthetic namespace rows, and source/query/window mismatches fail closed
• one invalid row rejects the entire response and emits no partial facts
• provider IDs, labels, annotations, workload identity, endpoints, collectors, and unknown raw metadata are discarded
• complete empty allocation maps emit zero facts; missing coverage is never estimated
• runtime cost is bounded local CPU and memory only, with no network, cloud API, storage, egress, logging-volume, or recurring-service spend

Verification

• go test -race -count=1 -cover ./internal/connector/opencost — pass, 93.2%
• projector fuzz target — pass, exactly 50,000 executions with four workers
• committed-diff CodeRabbit — zero findings after four documentation-contract corrections
• make ci — pass; zero lint findings and no reachable vulnerabilities
• make e2e-isolation — pass; PostgreSQL 18.4 forced RLS plus two 50,000-execution workspace fuzzers
• make release-check — pass; two reproducible four-platform snapshots, SPDX SBOMs, Homebrew output, and amd64/arm64 distroless OCI layout
• make e2e-kind — pass in 236.706s on pinned Kubernetes 1.36.1; clean teardown
• manual red-team and high-signal credential scan — zero unresolved findings/candidates
• pre-publication open security queues — Dependabot 0, code scanning 0, secret scanning 0

Commit integrity

• signed head: c7c1c3b24c15fafab41d49876d3c9badc84762ea
• exact parent: df28654b87ecfa1e491901ba8a3d718ba0825a49
• good ED25519 signature
• DCO sign-off present
• GSTACK-Checkpoint: 2026-07-18/e13-opencost-namespace-costs#1

Documentation

• README reviewed and updated with exact attachment, decimal, atomic-failure, and no-live-reader behavior
• E13 roadmap and Notion mirror updated without an epic-complete claim
• ADR 0011 records the decision and alternatives
• GSTACK session journal records the implementation and local proof

Summary by CodeRabbit

• New Features

  • Added OpenCost namespace cost fact projection for a specified UTC window.
  • Produces deterministic, per-namespace USD cost telemetry with exact decimal validation.
  • Supports complete empty responses by emitting zero facts.

• Bug Fixes

  • Rejects malformed, incomplete, duplicated, mismatched, or non-USD responses without producing partial results.

• Documentation

  • Documented the bounded OpenCost integration, validation rules, limitations, and accepted architecture decision.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fc2bcc3e-2b98-45fe-b9d6-751eef3572fa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an offline OpenCost namespace allocation projector with an exact USD protocol, strict response validation, deterministic FactCost emission, atomic failure behavior, boundary tests, fuzz coverage, and accompanying ADR, roadmap, README, and session documentation.

Changes

OpenCost namespace cost facts

Layer / File(s)	Summary
Projector contract and review boundary docs/adr/*, README.md, docs/EPICS.md, docs/SITH-NOTION.md, internal/connector/opencost/project.go, internal/connector/opencost/boundary_test.go	Defines allocation/namespace-usd-v1, the value-only projection types, trusted query constraints, and AST checks for the allowed production surface.
Response decoding and validation internal/connector/opencost/project.go	Decodes strict JSON, validates the envelope, query/window identity, namespace scope, cost literals, totals, bounds, duplicate keys, and atomic failure conditions.
Fact emission and adversarial verification internal/connector/opencost/project.go, internal/connector/opencost/project_test.go, sessions/*	Builds deterministic namespace graph facts and verifies normalization, identity binding, privacy filtering, empty results, tolerance handling, malformed inputs, no-partial-result behavior, and fuzz safety.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ProjectNamespaceCosts
  participant OpenCostAllocationResponse
  participant fleet_GraphFact
  Caller->>ProjectNamespaceCosts: provide trusted query and authorized response
  ProjectNamespaceCosts->>OpenCostAllocationResponse: decode and validate allocation envelope
  OpenCostAllocationResponse-->>ProjectNamespaceCosts: validated namespace rows and USD components
  ProjectNamespaceCosts->>fleet_GraphFact: construct deterministic cost facts
  fleet_GraphFact-->>Caller: validated facts or atomic error

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.04% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: projecting OpenCost namespace allocations.
Linked Issues check	✅ Passed	The projector, validations, tests, and docs align with #282's bounded offline namespace-allocation contract.
Out of Scope Changes check	✅ Passed	The changes stay within the OpenCost projector, test coverage, and related documentation, with no unrelated feature work.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gnanirahulnutakki/feat/e13-opencost-namespace-costs

---

_{Comment @coderabbitai help to get the list of available commands.}

[gnanirahulnutakki]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[gnanirahulnutakki]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.