feat(proof): proof-admin install bundle over the existing topic publish path (P0) by echobt · Pull Request #297 · CortexLM/cortex

echobt · 2026-09-14T11:07:33Z

Summary

Dynamic-topics P0 — remapped onto the existing admin publish path per the
Arch §11 hardcoding-inventory delta: cortex scoring and its DB are already
multi-topic, so P0 wraps what exists instead of inventing a parallel registry.

This PR must NOT be merged by the agent. Owner holds merge until the
staging A→Z run.

What this is now

A topic already has one home: the operator-signed TopicDocument
published through POST /v1/admin/proof/topics and persisted in
proof_topic_version (migration 0020). Its bindings are signed topic data
too — constraints.params carries the in-guest runner and its pinned pack
digest. This PR adds the missing procedure, not a second registry.

Step	Existing path reused
Sign	`xtask proof-topic` (sr25519, `base-proof-topic-v1`)
Acceptance	`TopicDocument::validate` + `verify_signature` — the same pair the admin route runs
Publish	`POST /v1/admin/proof/topics` (operator bearer)
Persist	`proof_topic_version` via `RlmStore::put_topic_version`
Custom id	`PROOF_VM_RUNNER_CUSTOM_IDS` + pack under `PROOF_VM_AGENT_EXPERIMENT_PACK_DIR`

Changes

RlmStore::latest_topics — a read-only registry view over the same
proof_topic_version rows (DISTINCT ON (topic_id) … ORDER BY version DESC), in both the Postgres and memory stores, pinned by the shared
contract test. No new table, no new column, no migration.
crates/proof-topic-bundle — the bundle carries the signed document
verbatim plus a host block that must agree with it. Runner / pack /
custom id are read from the document's own constraints.params via
proof-experiment::ExperimentBinding, so every binding has exactly one
copy. A host expectation that contradicts the document is a reject, never
an override.
bins/proof-admin — topic validate runs the same acceptance the
publish route runs; install --dry-run prints that publish call plus the
host env; topic list / topic show read the registry view.
Docs — docs/PROOF.md § Topic install bundles rewritten,
docs/COMPLETENESS.md row, docs/ARCHITECTURE.md bin entry.

Removed (the parallel table this slice had added)

Migration 0024_proof_topics.sql / the proof_topic table, db::topics, and
its integration tests — they duplicated proof_topic_version, which is
already the durable topic table. A second table would have been a second
source of truth for the same facts.

KEPT, as instructed

Runner rlm_fc_in_guest_harbor.
The proof-experiment anti-hardcode locks (untouched).
Signed-topic bindings stay topic data.

NOT P0 (per the delta)

Front-end debrand and the harbor-trials-v1 rename are P1; neither is
touched here.

Topics are RLM-based — the CLI only hands control to the RLM

The admin CLI's job is to ask the topic's RLM to install and set itself
up. The bundle carries an rlm section that owns everything
topic-specific, and Rust never interprets it:

RLM-owned	What it is
`rules`	anti-cheat rules the RLM ticks before any paid inference
`migrations`	SQL migrations the topic's install needs
`apis`	APIs the topic exposes
`submission_format`	the shape a miner submits
`scoring`	how the topic scores

The bundle crate checks the section's shape only (object or array,
bounded at 256 KiB) and carries it byte-for-byte into the plan as
rlm_install. It does not know what a rule, migration, API, submission
format, or scoring function means — recognising them would mean the crate
knows the topic. Unknown content is not an error.

The install plan leads with the hand-off and names the RLM's own lifecycle
steps (provision -> propose_rules -> baseline, the existing TopicSetup
driver), then the publish call and host env. The CLI does not run those steps
and does not read into the section.

Two guard tests enforce the boundary, both verified to fail on what they
forbid:

no_topic_literal_appears_in_this_crates_logic (bundle) and
the_cli_does_not_bake_in_topic_behavior (CLI) scan the non-test source
with comments stripped — prose may explain the rule, a literal in a
let/match/if is caught. Injecting topic_id == "tb4" fails the CLI
guard.
The CLI guard also forbids naming a metric, a task, a benchmark, or the RLM
section's own keys. The first draft enumerated
rules/migrations/apis/submission_format/scoring in its output and the
guard caught it — so the CLI now says the section is handed over without
listing what is in it.

Seed ids stay strings: tb4 and tbench appear only in fixtures, operator
examples, and docs. The bundle crate's non-test source has no topic literal
at all.

Owner defaults (locked)

Default	Value	Where
First topic slug	`tb4`	the signed document's `id`
Temporary alias	`tbench`	`proof_topic_alias` (migration `0024`), row `tbench → tb4`
Storage	shared challenge DB, `topic_id` discriminant	`proof_topic_version` — no per-topic schema
Metal install	Owner-only, staging first	`--owner-metal-ack` gate
Custom id	`tbench`	the document's `metric.custom_id`

Alias map (0024_proof_topic_alias.sql): a row is alias → topic_id
and nothing else — no name, no pins, no status, no document. Everything else
stays in proof_topic_version, so an alias cannot drift from the topic it
names and retiring it is just deleting the row. This is deliberately not a
second topic table. Resolution is fail-closed in both stores: an alias whose
topic has no published version resolves to nothing, never to an empty
document, and put_alias refuses an unpublished topic outright. base_app
gets DELETE here (unlike the journal tables) because retiring a temporary
alias is the intended end state.

tbench is two different bindings and they are not the same mapping: the
temporary alias (retire with topic alias rm tbench once links move)
and the runner registry's custom id (PROOF_VM_RUNNER_CUSTOM_IDS=tbench,
the scoring binding, permanent).

Owner-only metal gate: --env metal is refused (exit 2) without
--owner-metal-ack, which asserts an Owner authorized the install and that
staging passed for that bundle. The refusal names the staging command to run
first. --env staging is never gated. The gate is an operator assertion, not
a verified precondition — it exists so a live target cannot be reached by a
default or a copy-pasted staging command.

P0 scope — deliberately not done

No behavior change. No new table, no new route, no allocator change,
and nothing on a scoring path changed. latest_topics is a read-only view.
A real install is not implemented (exit 3): publishing needs the
operator bearer, which stays on the host. install --dry-run prints the
call for an operator to run.
topic enable / disable / seal are stubs (exit 3) pointing at the real
answer: a topic's lifecycle is the signed document's status, so re-sign
and re-publish.

HOLD — do not merge

Owner holds the merge until the staging A→Z run. Left open unmerged even
though CI is green.

Greptile

Greptile review requested
Findings fixed or answered

Test plan

Two failures in my sandbox are pre-existing and unrelated (both reproduce
on a clean tree):
crates/db/tests/gateway_store.rs (3 tests, fail against a local Postgres 18
that CI does not have) and
proof-challenge-bin::seed_pf_allocator_refuses_boot_when_a_topic_dir_cannot_be_read
(relies on chmod 000 blocking reads, which does not hold as root; verified
passing as a non-root user, which is how CI runs).

Risk

Low. Two things ship, both bounded and both stated here rather than
implied:

Schema: crates/db/migrations/0024_proof_topic_alias.sql only. It
adds proof_topic_alias (alias → topic_id + a topic_id index) and a
BEFORE INSERT/UPDATE trigger pair (proof_topic_alias_no_shadow,
proof_topic_version_no_shadow) that makes an alias collision with a
published slug fail closed in both directions. That trigger sits on the
publish path — INSERT into proof_topic_version — and is a
publish-path integrity guard, not scoring math: it cannot change a score,
a payout, or a sealed vector. The migration does not ALTER or DROP
anything; the 0020 tables keep their columns, keys, and grants.

Code: no route change, no scoring change, no allocator change, no
BASE_* / deployed-path / crypto-domain-tag change. The CLI reads existing
proof_topic_version rows and prints an operator procedure; a real install is
still exit 3.

Earlier revisions of this body claimed "no schema change" and described a
0024 topics table that was removed in the remap. Both were wrong for HEAD
and are corrected here and in docs/PROOF.md / docs/COMPLETENESS.md.

Naming

I did not rename BASE_* environment variables, deployed host paths,
GHCR baseintelligence/base package names, or base-*-v1 cryptographic
domain tags.

Dynamic-topics slice 1 (Arch pins): a per-topic install registry and the operator CLI that writes it. No behavior change — nothing on a scoring path reads the new table, no route and no allocator changes, and the compiled-in topic bindings stay (P4). - db: migration 0024 adds `proof_topic` to the shared challenge DB, keyed by `topic_id` (the discriminant), with `display_name`, `version`, `environment`, `runner_id`, `aliases`, `enabled`, `config` JSONB, `pin_rlm`, `pin_experiment`, `pack_digest`, `n_concurrent`, `sealed_custom_value`, `schema_version`, the bundle verbatim + its digest, and timestamps. Shape CHECKs guard the slug, the `sha256:<64 hex>` pins, a finite baseline, and the alias array. Mutable (enable/disable, re-install, seal) so `base_app` gets SELECT/INSERT/UPDATE and never DELETE: a topic is disabled, never dropped. - db::topics: upsert / list / get over runtime sqlx (no compile-time DB), plus DB-gated integration tests (install, ordering, re-install keeps created_at and does not silently disable, CHECK refusals, app-role grants). - crates/proof-topic-bundle: the topic install bundle schema v1 — parse, validate, canonical digest, install plan. Unknown keys are refused, every pin is `sha256:<64 hex>` or absent (never invented), and an in-guest `runner_id` without a `pack_digest` is refused. - bins/proof-admin: `topic validate` (no writes), `topic install [--dry-run]` (dry-run needs no database), `topic list`, `topic show`. Installing writes `enabled = false`; `topic enable` / `disable` / `seal` exit 3 with a clear "not implemented in this slice". Process-level tests cover validate, dry-run, the env mismatch, the missing-database path, and the stubs. - docs: PROOF.md § Topic install bundles, COMPLETENESS row, ARCHITECTURE bin. Arch defaults: first topic slug `tb4` with alias `tbench`; shared DB with a `topic_id` discriminant. Alias resolution, routes (P1), the allocator (P2), the full install (P3), and removing the hardcoded bindings (P4) are later slices. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

+                  if opts.json {
+                      let body = serde_json::json!({
+                          "ok": true,
+                          "installed": true,
+                          "topic_id": plan.topic_id,
+                          "environment": plan.environment.as_str(),
+                          "bundle_digest": plan.bundle_digest,
+                          "enabled": false,
+                      });
+                      println!(
+                          "{}",
+                          serde_json::to_string_pretty(&body).unwrap_or_else(|_| "{}".into())
+                      );
+                      return Ok(());
+                  }
+                  print_plan(&plan);
+                  println!();
+                  println!(
+                      "Installed {} (DISABLED). Enabling is a later slice: nothing scores this topic yet.",

+              fn is_digest(s: &str) -> bool {
+                  s.strip_prefix(DIGEST_PREFIX)
+                      .is_some_and(proof_canon::is_hex64)
+              }

+              /// A `u32` that fits the row's `INTEGER` columns. The bundle's own bounds keep
+              /// every value far below `i32::MAX`, so this only guards the cast.
+              fn clamp_i32(v: u32) -> i32 {
+                  i32::try_from(v).unwrap_or(i32::MAX)

+                  CONSTRAINT proof_topic_aliases_bound CHECK (cardinality(aliases) <= 8),
+                  CONSTRAINT proof_topic_aliases_shape CHECK (
+                      cardinality(aliases) = 0
+                      OR array_to_string(aliases, ',') ~ '^[a-z0-9][a-z0-9-]{1,62}(,[a-z0-9][a-z0-9-]{1,62})*$'
+                  ),
+                  CONSTRAINT proof_topic_aliases_not_self CHECK (NOT (topic_id = ANY (aliases))),

+                      let canonical = self.canonical()?;
+                      if canonical.len() > MAX_CONFIG_BYTES {
+                          return Err(BundleError::ConfigTooLarge(canonical.len()));
+                      }

+                  // would be exactly the mistake that leads to a surprise on a live host.
+                  let persisted = db::get_topic(&pool, &plan.topic_id)
+                      .await
+                      .map_err(|e| Failure::Error(format!("read back {}: {e}", plan.topic_id)))?
+                      .ok_or_else(|| {
+                          Failure::Error(format!(
+                              "install {} reported success but the row is missing",
+                              plan.topic_id
+                          ))
+                      })?;

+                      "       --data-binary @{} \\",
+                      signed_document_hint(bundle_path)
+                  );

+                      "jq '.topic' {bundle} > /tmp/proof-topic-document.json && \
+                       proof-admin topic validate --bundle {bundle} --pin config/proof-pin.toml"
+                  );
+                  let publish = format!(
+                      "curl -sS -X POST \\\n  \
+                       -H \"Authorization: Bearer $PROOF_ADMIN_TOKEN\" \\\n  \
+                       -H 'content-type: application/json' \\\n  \
+                       --data-binary @/tmp/proof-topic-document.json \\\n  \

+                  async fn put_alias(&self, alias: &str, topic_id: &str) -> Result<(), StoreError> {
+                      // Fail closed before the write: an alias must name a topic that
+                      // actually has a published version, or resolution would hand back
+                      // nothing and look like an unknown topic.
+                      if self.latest_topic(topic_id).await?.is_none() {
+                          return Err(StoreError::Malformed(format!(
+                              "alias {alias:?} names topic {topic_id:?}, which has no published version"
+                          )));
+                      }
+                      sqlx::query(
+                          "INSERT INTO proof_topic_alias (alias, topic_id) VALUES ($1, $2) \
+                           ON CONFLICT (alias) DO UPDATE SET topic_id = EXCLUDED.topic_id, \
+                           updated_at = now()",
+                      )
+                      .bind(alias)
+                      .bind(topic_id)
+                      .execute(&self.pool)
+                      .await?;
+                      Ok(())
+                  }

+                      IF EXISTS (SELECT 1 FROM proof_topic_version WHERE topic_id = NEW.alias) THEN
+                          RAISE EXCEPTION 'alias % is already a published topic id', NEW.alias
+                              USING ERRCODE = 'check_violation';
+                      END IF;
+                  ELSE
+                      IF EXISTS (SELECT 1 FROM proof_topic_alias WHERE alias = NEW.topic_id) THEN

+                  let mut second = doc.clone();
+                  second.id = "race-slug-v0".into();
+                  store.put_topic_version(&second).await.unwrap();
+                  // Race an alias claim against a *different* alias claim for the same slug.
+                  // One must win; the loser must be refused, never silently applied.
+                  let slug = "race-slug-v0";
+                  let a = store.clone();
+                  let b = store.clone();
+                  let (ra, rb) = tokio::join!(
+                      async move { a.put_alias(slug, &doc.id).await },
+                      async move { b.put_alias(slug, "race-slug-v0").await },
+                  );

+                  // Releasing A lets B proceed; the invariant still holds because A's claim
+                  // is then visible and B is refused.
+                  holder.rollback().await.expect("rollback holder");
+                  drop(publisher);

+              pub struct RlmSection {
+                  /// Anti-cheat rules the RLM ticks before any paid inference. Opaque.
+                  #[serde(skip_serializing_if = "Option::is_none")]
+                  pub rules: Option<serde_json::Value>,
+                  /// SQL migrations the topic's install needs. Opaque.
+                  #[serde(skip_serializing_if = "Option::is_none")]
+                  pub migrations: Option<serde_json::Value>,
+                  /// APIs the topic exposes. Opaque.
+                  #[serde(skip_serializing_if = "Option::is_none")]
+                  pub apis: Option<serde_json::Value>,
+                  /// The topic's submission format. Opaque.
+                  #[serde(skip_serializing_if = "Option::is_none")]
+                  pub submission_format: Option<serde_json::Value>,
+                  /// The topic's scoring definition. Opaque.
+                  #[serde(skip_serializing_if = "Option::is_none")]
+                  pub scoring: Option<serde_json::Value>,

+              flow:
+              ```bash
+              cargo sqlx migrate run   # or: restart the service with BASE_DATABASE_URL set

+                      let parsed: serde_json::Map<String, serde_json::Value> =
+                          serde_json::from_str(text).map_err(|e| BundleError::Parse(e.to_string()))?;
+                      for (key, value) in &parsed {

Uh oh!

Conversation

echobt commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this is now

Changes

Removed (the parallel table this slice had added)

KEPT, as instructed

NOT P0 (per the delta)

Topics are RLM-based — the CLI only hands control to the RLM

Owner defaults (locked)

P0 scope — deliberately not done

HOLD — do not merge

Greptile

Test plan

Risk

Naming

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

echobt commented Sep 14, 2026

Uh oh!

greptile-apps Bot Sep 14, 2026

echobt commented Sep 14, 2026 •

edited

Loading

greptile-apps Bot commented Sep 14, 2026 •

edited

Loading