feat(ODEngine): open a model package and run it without unpacking it

An engine's model has always been a path to a password-protected zip:
ANSODBase inflates it into a folder, and every engine then picks out
train_last.onnx, classes.names and model_config.json. A .ansmodel
package replaces all four with one sealed file, and this is the part
that turns it back into what the engines already understand.

ANSODBase::LoadModel and ::Initialize now recognise a .ansmodel path and
take a second route: the package is opened with the process keyring, the
model is decrypted into memory, and the classes, task and input geometry
come out of the manifest instead of loose files. Nothing is extracted,
so the unprotected model never touches the disk — which is the reason
the format exists, and it is one function's job to keep.

The engines follow it down. BasicOrtHandler gains a constructor that
takes the bytes rather than a path; it keeps a view of them, not a copy,
because the weights are in RAM either way once a session exists and a
copy would only double what every loaded model costs. The owner of the
plaintext is ANSODBase, which holds it for as long as the engine object
lives — that is what lets the DirectML recovery path rebuild a session
after a driver fault — and wipes it on teardown.

Wired through ANSONNXYOLO (and so the classification facade), ANSONNXOBB,
ANSONNXPOSE, ANSONNXSEG and YOLO12OD. YOLOOD is left alone: it loads
darknet weights and OpenCV DNN graphs, neither of which the writer
produces. A zip still loads exactly as before, on every engine.

Keys come from SetProcessModelKeys, as in ANSMINDCORE, with the same
development fallback from the environment. With none set, a package is
refused with a sentence saying so and every zip still works, so a build
made before the key ceremony runs everything except packages.

The engine layer needs CUDA to compile, so the contract it depends on is
checked where it can be: ANSModelPackage-UnitTest now opens the fixture
ANSMINDCORE wrote through the same glue ANSODBase uses, and covers the
refusal a keyless build gives. 32 checks, no failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-12 22:21:39 +10:00
co-authored by Claude Opus 5
parent 6c164c3d0f
commit 080910c8ac
13 changed files with 723 additions and 33 deletions
+212
View File
@@ -0,0 +1,212 @@
#ifndef ANSMODELOPEN_H
#define ANSMODELOPEN_H
#pragma once
// ANSModelOpen — the one place that knows how a model package reaches an engine.
//
// An engine's "model" has always been a path: a password-protected zip that
// ANSODBase inflates into a folder, after which the engine picks out
// train_last.onnx, classes.names and model_config.json. A .ansmodel package
// replaces all four with one sealed file, and this header is what turns it
// back into the things the engines already understand — the model's bytes, the
// class list, the task and the input size.
//
// THE PLAINTEXT NEVER REACHES THE DISK. That is the whole reason the format
// exists. OpenModelPackage decrypts into a buffer the caller owns; the caller
// hands that buffer to a session and wipes it. Nothing here writes a file.
//
// WHERE THE KEY COMES FROM. The product sets it once at startup with
// SetProcessModelKeys(): the base PRIVATE key packages are sealed to, and the
// root PUBLIC key that vouches for a release signing key. Nothing here reads a
// key out of the package or off the disk. With no keys set, a package is
// refused with a sentence that says so, and every existing zip still loads — a
// build from before the key ceremony runs everything except packages.
//
// The base private key must never sit in the binary as one contiguous
// constant; assembling it is the job of whatever calls SetProcessModelKeys,
// not of this header, which is why this header has no key material in it.
//
// The development fallback (ANSCORE_MODEL_KEY_ID / ANSCORE_MODEL_BASE_PRIVATE
// / ANSCORE_MODEL_ROOT_ID / ANSCORE_MODEL_ROOT_PUBLIC, all base64) exists so
// the path can be exercised before that ceremony exists. It is read once and
// announced, because a key that came from the environment is not the key a
// shipped product should be using.
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <mutex>
#include <string>
#include <vector>
#include "ANSModelPackage.h"
namespace ANSCENTER {
namespace modelpkg {
// ── the keys this process opens packages with ─────────────────────────────
namespace detail {
inline std::mutex& keysMutex() {
static std::mutex m;
return m;
}
inline Keyring& keyringStorage() {
static Keyring ring;
return ring;
}
inline bool keyFromB64(const char* b64, Key& out) {
if (!b64 || !*b64) return false;
std::vector<uint8_t> raw;
if (!bits::base64Decode(b64, raw) || raw.size() != out.size()) return false;
std::memcpy(out.data(), raw.data(), out.size());
return true;
}
// Development only: keys from the environment, once, and said out loud.
inline void loadEnvKeysOnce(Keyring& ring) {
static bool done = false;
if (done) return;
done = true;
const char* id = std::getenv("ANSCORE_MODEL_KEY_ID");
const char* priv = std::getenv("ANSCORE_MODEL_BASE_PRIVATE");
Key k{};
if (id && *id && keyFromB64(priv, k)) {
ring.addX25519(id, k);
std::fprintf(stderr,
"[modelpkg] base key %s taken from the environment - for "
"development, not for a shipped build\n",
id);
}
const char* rootId = std::getenv("ANSCORE_MODEL_ROOT_ID");
const char* rootPub = std::getenv("ANSCORE_MODEL_ROOT_PUBLIC");
Key r{};
if (rootId && *rootId && keyFromB64(rootPub, r)) {
ring.addRoot(rootId, r);
std::fprintf(stderr,
"[modelpkg] root key %s taken from the environment\n",
rootId);
}
}
} // namespace detail
inline void SetProcessModelKeys(Keyring ring) {
std::lock_guard<std::mutex> lk(detail::keysMutex());
detail::keyringStorage() = std::move(ring);
}
inline Keyring ProcessModelKeys() {
std::lock_guard<std::mutex> lk(detail::keysMutex());
Keyring& ring = detail::keyringStorage();
detail::loadEnvKeysOnce(ring);
return ring; // by value: the caller may open on another thread
}
// True once this build can open anything at all. A product that has not had
// keys installed should say "this build cannot open model packages" rather
// than let every load fail one at a time.
inline bool HaveProcessModelKeys() {
const Keyring ring = ProcessModelKeys();
return !ring.x25519.empty() || !ring.keys.empty();
}
// ── recognising one ───────────────────────────────────────────────────────
inline bool IsPackagePath(const std::string& path) {
return path.size() > 9 &&
path.compare(path.size() - 9, 9, ".ansmodel") == 0;
}
// ── what an engine needs out of one ───────────────────────────────────────
// Everything the inflated folder used to carry, in the shape the engines read
// it: the model itself, the classes in order, and the geometry that
// model_config.json held.
struct OpenedModel {
std::vector<uint8_t> model; // decrypted; wipe it once loaded
std::vector<std::string> classes;
std::string task; // detection | classification | segmentation | obb | pose
std::string family; // yolo | yolo10 | rfdetr
std::string runtime; // onnx | openvino-ir
std::string legacyMarker; // what the zip would have carried
std::string name; // what to call this model in a log
int inputWidth = 0; // 0 when the package does not say
int inputHeight = 0;
std::string warning; // show it; the model still loaded
void wipe() {
if (!model.empty()) std::memset(model.data(), 0, model.size());
model.clear();
model.shrink_to_fit();
}
};
// Read what a package says about itself without decrypting the model. Cheap
// enough to call on a folder full of packages.
inline bool DescribeModelPackage(const std::string& path, OpenedModel& out,
std::string& err) {
Package pkg;
if (!open(path, ProcessModelKeys(), pkg, err)) return false;
const Json& m = pkg.manifest;
out.task = m.value("task", std::string("detection"));
out.family = m.value("family", std::string());
out.runtime = m.value("runtime", std::string("onnx"));
out.legacyMarker =
m.value("legacy", Json::object()).value("marker", std::string());
out.warning = pkg.warning;
out.classes.clear();
for (const auto& c : m.value("classes", Json::array()))
out.classes.push_back(c.value("name", std::string()));
const Json in = m.value("input", Json::object());
out.inputWidth = in.value("width", 0);
out.inputHeight = in.value("height", 0);
out.name = m.value("project", std::string());
if (out.name.empty()) out.name = path;
return true;
}
// Open one all the way: the description above, plus the model's bytes.
//
// The caller owns those bytes and should wipe them (OpenedModel::wipe) the
// moment the session has copied what it needs.
inline bool OpenModelPackage(const std::string& path, OpenedModel& out,
std::string& err) {
if (!HaveProcessModelKeys()) {
err = "this build has no model-package key, so it cannot open " + path;
return false;
}
Package pkg;
if (!open(path, ProcessModelKeys(), pkg, err)) return false;
const std::string entry = pkg.entryPayloadId();
if (entry.empty()) {
err = "the package names no model to run";
return false;
}
if (!readPayload(pkg, entry, out.model, err)) return false;
const Json& m = pkg.manifest;
out.task = m.value("task", std::string("detection"));
out.family = m.value("family", std::string());
out.runtime = m.value("runtime", std::string("onnx"));
out.legacyMarker =
m.value("legacy", Json::object()).value("marker", std::string());
out.warning = pkg.warning;
out.classes.clear();
for (const auto& c : m.value("classes", Json::array()))
out.classes.push_back(c.value("name", std::string()));
const Json in = m.value("input", Json::object());
out.inputWidth = in.value("width", 0);
out.inputHeight = in.value("height", 0);
out.name = m.value("project", std::string());
if (out.name.empty()) out.name = path;
return true;
}
} // namespace modelpkg
} // namespace ANSCENTER
#endif // ANSMODELOPEN_H