Skip to content

docs: align Optima documentation with the current architecture - #1

Merged
ShivanshuPurohit merged 1 commit into
mainfrom
codex/refresh-optima-docs-20260716
Jul 16, 2026
Merged

docs: align Optima documentation with the current architecture#1
ShivanshuPurohit merged 1 commit into
mainfrom
codex/refresh-optima-docs-20260716

Conversation

@ShivanshuPurohit

Copy link
Copy Markdown
Collaborator

Summary

  • refresh the architecture, miner, validator, engine, security, and reference documentation against Optima source snapshot f8be20a4
  • add a dedicated direct-artifact architecture page covering provider identity, sealed CUBIN publication, ABI validation, runtime loading, lifecycle, isolation, and current implementation gaps
  • update the public CLI surface, manifest schema, settlement/cohort semantics, evidence authority, weight publication, and release workflow
  • separate evergreen engineering contracts from dated implementation evidence and historical change records

Why

The Optima implementation moved substantially beyond the previous documentation pin. Several pages still described retired commands or older state transitions, while some release and evidence prose attributed deployment-level guarantees to lower-level primitives that do not establish them alone.

This refresh makes the documentation source-grounded and neutral: active pages now describe invariants, typed authority boundaries, failure behavior, retained evidence, and explicit production prerequisites. Chronology is confined to the changelog and the dated state-of-record ledger.

Impact

Engineers and operators now have one consistent description of:

  • the current 14-command CLI and supported contribution workflow
  • registered-target and discovery settlement outcomes, including cohort winner and HOLD behavior
  • durable qualification evidence versus in-run-only diagnostics
  • direct-artifact and sealed-CUBIN execution boundaries
  • release preparation, registry, host-policy, receipt, and AOT evidence requirements
  • known implementation gaps that prevent treating the current checkout as release-ready

This PR changes documentation only; it does not alter Optima runtime behavior.

Review note

The dated state-of-record targets local Optima commit f8be20a43708efd830b7b1dae88f00ffaf532ad5 on codex/audit-gpu-readiness-20260716. At the snapshot time, no origin/* ref in the Optima source repository contained that commit; the ledger states this explicitly.

Validation

  • PYENV_VERSION=sn120 python scripts/check_docs.py — 59 Markdown files passed
  • PYENV_VERSION=sn120 mkdocs build --strict — passed
  • git diff --check — clean
  • all 109 unique linked Optima source paths resolve locally
  • rendered architecture, evidence, release, and state pages were inspected without horizontal overflow
  • Optima source suite at the documented snapshot: 1,951 passed, 19 skipped

@ShivanshuPurohit
ShivanshuPurohit marked this pull request as ready for review July 16, 2026 08:50
@ShivanshuPurohit
ShivanshuPurohit merged commit b5133ba into main Jul 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant