# Data Olympus 0.6.0 Expanded Release Design

Status: Approved by the operator on 2026-07-18

## 1. Context and scope

RC.1 was rejected because it was built from the wrong source revision. RC.2
corrected that defect and passed the kn-dev canary, but it is held because the
0.6.0 scope now includes the broader product-quality tranche.

The expanded release includes:

* Issue #82, executable OKF conformance against reference tooling.
* Issue #150, minimal default MCP tools with on-demand tool search.
* Issue #151, first-class stable and candidate release channels.
* Issue #157, a PyPI-first quickstart.
* Issue #158, benchmark provenance and a reproduction receipt.
* Dependabot pull requests #159 through #163.
* The Glama, index-hardening, metadata, and security work already present on the
  integration branch.

The release remains one delivery train. Independently reviewed slices are
followed by exact-revision integration review, a new candidate, a kn-dev canary,
and explicit human promotion.

## 2. Goals and non-goals

The release must:

* Reduce default MCP tool-list context without removing capabilities.
* Prove documented OKF compatibility with executable upstream tooling.
* Make candidates installable through every supported distribution path.
* Preserve exact source provenance across candidate and stable artifacts.
* Make the primary installation path independent of a source checkout.
* State benchmark provenance before presenting headline results.
* Include every currently open dependency update with risk-appropriate tests.
* Keep implementation, documentation, and external release contracts aligned.

The release will not:

* Add new MCP authorization semantics.
* Treat tool-list visibility as an authorization boundary.
* Claim independent benchmark validation.
* Vendor the upstream OKF implementation.
* Publish nightly or development builds to PyPI.
* Claim atomic publication across independent registries. It provides
  fail-closed gates and deterministic reconciliation instead.

## 3. Delivery sequence

Work lands serially on the existing integration branch because the affected
features overlap packaging, workflows, tests, and documentation.

1. Land development-only updates #159, #160, and #162.
2. Land runtime updates #163 and #161 with separate validation.
3. Implement tool discovery and compatibility evidence for #150.
4. Implement executable OKF conformance for #82.
5. Implement complete candidate and stable channels for #151.
6. Implement the PyPI-first quickstart and clean-environment smoke test for
   #157.
7. Implement benchmark provenance and receipts for #158.
8. Reconcile all affected documentation and release notes.
9. Run exact-revision CI, security clearance, and integration review before
   cutting RC.3 or a later candidate.

FastMCP and Regex are runtime changes, not routine tooling changes:

* FastMCP must resolve to a version that provides the tested search transform.
  The supported range and lockfile must guarantee that API.
* Regex executes on the secret-scanning write path. Its update requires timeout,
  rejection, false-positive, and catastrophic-backtracking regression tests.

## 4. MCP tool discovery

### 4.1 Modes

`KB_TOOL_DISCOVERY_MODE` supports:

* `search`, the default, which exposes a governing core and synthetic discovery
  tools.
* `all`, which bypasses the transform and exposes every native tool.

Any other value is a startup error. The server fails closed with a useful
message.

The default native tools are:

* `kb_consult`
* `kb_search`
* `kb_get`
* `kb_health`
* `kb_gate_check`
* `kb_record_event`
* `kb_session_recap`

The transform adds:

* `tool_search`
* `call_tool`

The implementation configures `tool_search` explicitly rather than relying on
the FastMCP default name. Search mode filters the `tools/list` response; it does
not disable or unregister native tools. Using `enabled=False` or an equivalent
mechanism that removes original-name call routing does not satisfy this design.

### 4.2 Compatibility

Tools omitted from `tools/list` remain available through `tool_search` and
`call_tool`. Original-name `tools/call` invocation must also remain valid. This
must be proven over the MCP wire protocol. If FastMCP cannot preserve it, the
release is blocked until the behavior is implemented safely or this design is
revised and reapproved.

Fixed-name consumers are inventoried and classified as:

* Always-visible native calls.
* Direct hidden native calls.
* Search followed by proxy calls.

Every known fixed-name consumer needs an integration test or an external
verification receipt. `all` remains the migration escape hatch for unknown
clients.

Wire-level acceptance tests cover these as distinct paths:

* A hidden native tool succeeds when invoked by its original name through
  `tools/call`.
* `tool_search` discovers that tool and `call_tool` invokes it successfully.

Visibility changes discovery only. Hidden tools retain their annotations,
authentication, and authorization. Tests must confirm search and proxy calls
cannot bypass those controls. Release notes identify this intentional pre-1.0
discoverability change and its compatibility mode.

## 5. Executable OKF conformance

The suite pins the Google OKF repository to an immutable commit in a
machine-readable configuration file. CI checks out that exact revision and
records it in test output.

The suite tests both directions:

1. The upstream reference consumer opens the Data Olympus example bundle and
   completes its documented path without schema or parsing failure.
2. Data Olympus lints, indexes, and reads a sample bundle from the pinned
   upstream revision.

Fixtures record:

* Upstream repository URL.
* Upstream commit SHA.
* Source path.
* Checksum.
* License provenance when copied into this repository.

CI never uses a floating upstream branch. A scheduled freshness check opens or
updates one tracking issue when the pin needs review. It never updates the pin
or compatibility claims automatically. README, SPEC, comparison, and adoption
claims describe only what the executable suite proves.

## 6. Release channels

### 6.1 Public channel model

| Surface | Candidate | Stable |
| --- | --- | --- |
| GHCR immutable | `0.6.0-rc.N` | `v0.6.0` |
| GHCR moving | `rc` | `stable` and `latest` |
| PyPI immutable | `0.6.0rcN` | `0.6.0` |
| GitHub | `0.6.0-rc.N` prerelease | `v0.6.0` release |

The internal canary channel remains independently movable and is never proof of
public stable promotion.

### 6.2 Source identity

The candidate workflow resolves its input to one 40-character source SHA before
building. The candidate and stable Git tags point to that same SHA. Stable
promotion requires the SHA to be contained in `main`; it cannot substitute a
merge commit or moving branch.

The source tree carries the stable base version. The candidate Python build uses
an isolated `to-delete/release-build` copy and applies a tested version-only
overlay producing `0.6.0rcN`. The source checkout and commit remain unchanged.
The overlay script emits its before and after values and fails if any unrelated
tracked content changes.

### 6.3 Artifact equivalence

OCI stable promotion re-tags the verified candidate digest. Rebuilding is not
allowed.

Python stable promotion rebuilds from the same source SHA because candidate and
stable wheels necessarily have different version metadata. CI unpacks both and
requires:

* An identical importable `data_olympus` payload.
* Identical entry points, packaged enforcement files, licenses, and non-version
  metadata.
* Differences limited to distribution names, the version in `METADATA`, and the
  corresponding `RECORD` hashes.
* An identical dependency lock hash.

The comparison normalizes the version-bearing `.dist-info` directory name,
removes `METADATA` version fields and `RECORD` entries affected by those fields,
and then compares the remaining normalized path and content hashes. Any
unrecognized difference fails the promotion.

The GitHub prerelease retains candidate distributions and a provenance manifest
for the stable comparison.

### 6.4 Candidate state machine

1. Resolve and validate the exact source SHA.
2. Compute the next RC and verify availability on GHCR, PyPI, and GitHub.
3. Run required CI, security, packaging, and provenance gates.
4. Build and smoke-test the image, wheel, and source distribution.
5. Publish immutable GHCR and PyPI candidate artifacts.
6. Read both registries back and verify versions, hashes, and source identity.
7. Move the GHCR `rc` channel.
8. Create the GitHub prerelease with artifacts and provenance attached.

If one immutable upload succeeds and another fails, the workflow does not move
the candidate channel or create the prerelease. A rerun verifies existing
artifacts and reconciles the missing publication.

### 6.5 Stable state machine

Stable promotion requires:

* The candidate SHA is contained in `main`.
* Required CI is green for that exact SHA.
* Security clearance is current.
* Independent integration review approves that SHA.
* Candidate registry verification is green.
* The kn-dev receipt identifies the candidate image digest.
* The stable version is free on every registry.
* Human approval names the candidate tag and source SHA.

After those gates, the workflow:

1. Creates the stable Git tag at the candidate SHA.
2. Builds and compares stable Python distributions.
3. Publishes stable PyPI artifacts.
4. Re-tags the candidate OCI digest as the stable tag and moving channels.
5. Verifies both registries.
6. Creates the stable GitHub release after both surfaces are complete.

Partial publication remains a visible failed workflow and must be reconciled
before release announcement.

### 6.6 Trusted Publishing and rollback

The candidate upload uses PyPI Trusted Publishing with:

* Owner `knaisoma`.
* Repository `data-olympus`.
* Workflow `rc-publish.yml`.
* Environment `pypi`.

PyPI registration is a human prerequisite. RC.3 cannot run until the publisher
exists. The workflow uses OIDC and stores no PyPI credential.

The RC upload runs inline in `rc-publish.yml`, not through a reusable publishing
workflow, so PyPI validates the expected top-level workflow identity. Before
RC.3, the operator must also confirm that the `pypi` GitHub environment permits
the immutable RC tag or ref. The Trusted Publishing runbook lists
`rc-publish.yml` alongside the stable and fallback publishing workflows. If the
stable environment cannot safely admit candidate refs, RC publishing uses a
separate protected environment and a matching Trusted Publisher registration.

GHCR rollback repoints moving channels to a verified immutable digest. PyPI
versions cannot be replaced. A faulty version is yanked, documented, and
followed by a new RC or patch. Deletion is never used for version reuse.

## 7. PyPI-first quickstart

The primary quickstart uses Python 3.13 and starts with `uvx` for evaluation or
`uv tool install` for persistence. Source installation moves to contributor
documentation.

It covers:

* Stable and explicit candidate installation from PyPI.
* Bundle creation or selection.
* Setup checks.
* MCP startup and readiness.
* Agent client connection.
* Search and all tool-discovery modes.

Clean-environment CI installs the built wheel without a repository checkout and
verifies both entry points, packaged `_bin` files, setup checks, MCP startup,
health, default discovery, and the all-tools escape hatch.

## 8. Benchmark provenance

Documents with headline benchmark results state before those results that they
are maintainer-produced and not independently reproduced.

The reproduction command generates a JSON receipt with:

* Receipt schema version.
* Repository URL and benchmark source commit.
* Relevant source-tree hash.
* Python and operating-system environment.
* Dependency lock hash and resolved benchmark versions.
* Exact commands, seeds, and configuration.
* Input corpus, tokenizer, and model identities.
* Input and output checksums.
* The result summary used by generated documentation.

The receipt is generated, never edited by hand. CI reruns the deterministic path
and checks artifacts, documentation, and receipt fields for drift. Benchmark
numbers cannot change without a reproduction run and receipt update. Benchmark
and release provenance remain separate receipts.

## 9. Documentation and external contracts

Implementation reviews and updates, where affected:

* README and quickstart.
* Serving, operations, adoption, comparison, and Glama documentation.
* Benchmark documentation and generated tables.
* Changelog and 0.6.0 release notes.
* PyPI Trusted Publishing runbook.
* Release workflow comments and inputs.
* External governed release contracts consumed by automation.

The changelog date becomes the actual stable publication date. Rejected and held
candidates stay clearly marked.

External knowledge-base changes use the governed Data Olympus write API only.
They receive independent review before proposal and are verified after refresh.
No private operator identifiers or internal repository details are added to this
public repository.

## 10. Verification and acceptance

Each slice receives focused tests and independent review. Tool exposure and
publishing require explicit security review.

The final candidate gate requires:

* A clean worktree at the recorded source SHA.
* Full tests, formatting, lint, and strict typing.
* Documentation consistency checks.
* Package build, metadata validation, and clean-environment smoke tests.
* Executable OKF conformance.
* Benchmark drift and receipt checks.
* Zero open Dependabot, CodeQL, and secret-scanning alerts.
* Whole-branch approval bound to the exact SHA.
* Candidate artifact provenance verification.
* Successful kn-dev canary and rollback evidence.
* Ingress-level verification that default search mode advertises the governing
  core, discovers and invokes a hidden tool, and clears the enforcement gate.
* An ingress-level spot check that all mode restores the complete native list.
* Explicit human approval before stable promotion.

RC.2 evidence is historical only. Scope expansion invalidates its ship approval,
integration review, and readiness bundle. The new chain starts at RC.3 or later.

The design is accepted only when all scoped issues and dependency updates are
present, all distribution paths are testable, the same-source invariant is
enforced, documentation agrees with behavior, and the complete release gate
passes for the new exact revision.
