From registry to execution: shipping the Execution Router

For the last eight months, an Aigarth Cloud ANN was a record in a registry. You could browse it, deploy it, version it, and rate it. What you could not do, until this week, is run the same ANN two different ways and prove which result came from which execution. That changes today.

The shape of the problem

A registry is a list of promises. A platform is the thing that makes the promises run. The bridge from "this ANN exists" to "this ANN ran, here is the result, here is the proof" is what the Execution Router is.

The router is small. The contract is:

• Same ANN, two executors. A user picks Local or Qubic OC. The router dispatches. A failed OC execution is visibly failed: no silent fallback to local.
• Same input, deterministic result hash. Anyone with the manifest, the version, the input, and the output can re-derive the hash and confirm "this result came from this exact ANN version using this exact input."
• Same identity across both targets. The manifest is the canonical identity. The manifest hash is the version. The repository row is the provenance.

What we built, in one diagram

A registered ANN has a manifest. The manifest names an architecture. The architecture has an adapter. The adapter runs. The result is hashed. The hash is the proof. The proof is stored on the ANN execution row, alongside the work_id when the executor was Qubic OC.

   ANN
     │
     ▼
   ANNExecutionRequest
     │  manifest_hash + version + input + target
     ▼
   ExecutionRouter
     ├── target=local       → LocalANNExecutor  (in-process)
     └── target=qubic_oc    → QubicOCExecutor   → services/work

The router does not know what an ANN does. It only knows which executor handles which target. The executor does the work. The result hash is computed by a single helper that knows the manifest hash, the version, the input hash, the target, and the canonicalised output.

The manifest is the identity

An ANN is not its name, or its creator, or its repository. An ANN is its manifest. Two ANNs are the "same version" iff they have the samemanifestHash, which is a sha256 of the canonicalised manifest. The manifest covers id, name, version (semver with a v prefix), creator, architecture, model hash, input and output schemas, an optional benchmark, a repository URL, a commit SHA, a license, and a description.

The schema is strict. Unknown fields are rejected. Semver is enforced. The model hash is a 64-char lowercase hex string prefixed with sha256:. The 14 ANNs we seeded earlier this year do not all have manifests yet; the demo ANN we ship today does.

The local executor is honest

The local executor runs the ANN's adapter in the current process. No network call, no OC layer. Same input + same manifest + same architecture always produces the same output. The result hash is deterministic.

If no adapter is registered for the manifest's architecture, the executor falls back to a clearly labelled deterministic stub. The stub's output carries a fixture: true flag, so no caller can mistake it for a real inference. The verification status on a local run is alwayslocal_deterministic. We do not pretend that a local run is decentralised.

The Qubic OC executor is honest too

The Qubic OC executor submits the execution to services/work, the Work Runtime. The Work Runtime was built earlier this year for arbitrary workloads with replication verification. The OC executor uses it as-is: the work item carries the manifest hash, the input, and the algorithm slug aigarth-oc-algorithm. The work service schedules it, assigns a worker, runs the algorithm, verifies the result, and returns the work_id.

If the OC service is down, the executor throws. The route returns 503. The UI does not silently fall back to local. A failed decentralized execution must remain visibly failed. This is the rule we wrote down at the start of the project, and the rule we kept.

The Work Runtime is the engine, not a wrapper

The Qubic OC executor is a thin HTTP client over services/work. We did not build a new execution engine; the Work Runtime was already designed for this. The new piece is a small INTERNAL_TOKEN-guarded endpoint on the Work Runtime (POST /v1/internal/work/items) that the ANN service calls with the user's identity. Same shape, same replication, same verifier. The OC executor is 200 lines of TypeScript.

This is the path of least resistance we kept talking about. The Work Runtime existed. The algorithm registry existed. The verifier existed. The router just wires them together.

The OC processor package, in one breath

The Execution Router is the outbound side: Aigarth submits an ANN execution to the Work Runtime. The inbound side is the OC processor: a Qubic smart contract calls Aigarth, the 451/676 computors sign, the result is signed and returned. We shipped the inbound side as a new package, @aigarth/oc-processor, with the rate-limit, circuit-breaker, signature-verify, and result-signer pieces.

• registerAsProcessor(manifest) wires a processor into the registry. The manifest is the contract with the Qubic network.
• onInvocation(handler) is the runtime hook. The handler maps the invocation to a work item, the Work Runtime executes it, the result is signed.
• 3-layer rate limit (per-caller, per-processor, per-epoch) and a circuit breaker (CLOSED, OPEN, HALF_OPEN) borrowed from the AigarthPool M3/M4 patterns.
• 451/676 signature verify is shipped as a structural check in v1. The real Ed25519 verify is Phase 30+, behind the ADR 007 production gate.

The OC processor's mainnet exposure requires a security review and a public testnet validation. The mechanism is built. The gate is the gate.

The UI is a real vertical slice

The web app now has a /anns/[slug] page that fetches the ANN's manifest, the published repository, and the execution history. The Run panel has a target picker (Local, Qubic OC), a JSON input editor, a Run button that posts to /api/anns/[slug]/execute, and a polling loop that watches the execution reach a terminal state. The history table shows the last 20 runs with the verification status and the result hash.

The dashboard has a new /ann-execution page: the operator view of every ANN, every run, every verification, every work_id. The OC processor dashboard is at /oc, empty for now (the registry hydrates when the operator boots it in the gateway; Phase 30+ persists it).

The demo ANN is on purpose trivial

The demo is the BTC Direction Predictor v1. The architecture is a 5-day momentum rule on a 30-day price window. The adapter sums the last close minus the close from 5 days ago, normalises by the mean price, and emits up, down, or flat. It is not a real model. It is the smallest thing that exercises the entire pipeline end-to-end:

• Manifest: id, version, architecture, input/output schemas, model hash, repository, commit, license.
• Adapter: registered at boot, called by the local executor.
• Repository row: synthetic commit SHA from the manifest hash, kind seed, with a releaseUrl that encodes the architecture so the executor can find the adapter.
• Local run: deterministic, fast, returns the prediction in milliseconds.
• OC run: submits to the Work Runtime, polls until verified, returns the work_id and the result hash.
• Result hash: identical for both targets when the algorithm is deterministic. The OC executor uses the deterministic verification method (single re-run, not 3-way replication).

The BTC Direction Predictor exists to prove the pipeline works. It is not a product. A real predictor would be an MLP or a transformer. The fixture is the canary.

What we did not build (on purpose)

Three things are deferred, and we are being explicit about them so no one reads the UI and assumes more is operational than it is.

• GitHub publishing is a stub. ThePOST /v1/anns/:idOrSlug/github-publish route returns not_configured with a pointer to the env vars an operator needs to set. The seed attaches a synthetic repository row directly. The real GitHub App wire-up is Phase 30+, after the security review.
• The OC processor is not exposed as a public HTTPS endpoint. The package is a library. The gateway wire-up is Phase 30+.
• Economic policy runtime is schema-only. The ann_economic_policies and ann_epochs tables ship. The runtime that uses them is Phase 9/10 work, after the execution primitive is stable.

Numbers for the engineers

This delivery touches four services, one new package, one new migration, and one new public page. The breakdown:

• services/ann: 1 migration (0008), 4 new tables (ann_executions, ann_repositories, ann_economic_policies, ann_epochs), 5 new routes (execute, executions, executions/:id, repositories, github-publish), the Execution Router + 2 executors + the result-hash helper + the adapter registry + the BTC demo adapter + the execution service + the manifest types.
• services/work: 1 new internal route (POST /v1/internal/work/items) + (GET /v1/internal/work/items/:work_id), the canonical serializeWorkItem exported for cross-service callers.
• packages/oc-processor: the new package: types, canonicalisation, signature verify, rate limit, circuit breaker, result signer, work-runtime integration, registry, the full pipeline.
• packages/sdk: new anns.execute, anns.listExecutions, anns.getExecution, anns.listRepositories; new OcProcessors resource for the inbound side.
• apps/web: new /anns/[slug] page with the Run panel, three server proxies, the demo BTC seed.
• apps/dashboard: new /ann-execution and /ann-execution/[slug] pages, new /oc page, the SDK adapter.
• docs: new docs/ann-execution/README.md, new docs/oc-processor/README.md, full phase delivery report.
• Tests: 37 new tests in the oc-processor package, 38 new tests in services/ann (manifest, result-hash, router, BTC adapter, executions service). All pass; the existing 200+ in the ANN service still pass.

The bridge we crossed

Aigarth Cloud can now take an ANN from a developer's machine, give it a permanent identity, publish it openly, send it into the Work Runtime, and return a verifiable result. The GitHub publish is the only piece that is still a stub, and the manifest hash carries the identity regardless of where the artifact is stored.

The end state is no longer "an AI website." The platform deploys intelligence into a decentralized compute economy. The router is the seam between "I built an ANN" and "the network ran it, and here is the proof."

That is the bridge. The next one is the marketplace: staking, creator rewards, governance, and the economic policy runtime. Phase 30+.