Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat: revision pinning + opt-in SHA-256 verification for checkpoint loads (draft for #332)

Aashish59acf353b7a3
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index 246ff0f6..264ca9af 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -91,6 +91,8 @@ export interface AgentOptions {
provider: SessionProvider;
tok?: TokenizerLike;
cfg?: AgentCfg;
+ /** Commit SHA the artifacts were loaded from (pinned/requested or `x-repo-commit`); null for local dirs. */
+ revision?: string | null;
max_len?: number;
head_max_len?: number;
temperature?: unknown;
@@ -259,6 +261,7 @@ export class Agent extends HookRegistry {
hooksRaise: boolean;
cfg: AgentCfg;
provider: SessionProvider;
+ revision: string | null;
tok: TokenizerLike;
maxLen: number;
headMaxLen: number;
@@ -275,6 +278,7 @@ export class Agent extends HookRegistry {
super();
if (!opts || !opts.provider) throw new Error("Agent needs a provider");
this.provider = opts.provider;
+ this.revision = opts.revision ?? null;
// Hooks are opt-in; an unset hook list is a no-op. See hooks.ts.
this.hooks = normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd);
this.hooksRaise = opts.hooksRaise ?? true;
@@ -545,6 +549,13 @@ export class Agent extends HookRegistry {
numThreads?: number;
/** Per-language temperature overrides; see AgentOptions.lang_temperatures. */
lang_temperatures?: AgentOptions["lang_temperatures"];
+ /** Commit SHA/branch/tag to fetch; published checkpoints pin to a reviewed SHA by default. */
+ revision?: string | null;
+ /**
+ * Opt-in `{artifact name: SHA-256 hexdigest}` check before any artifact is parsed
+ * or executed. A missing artifact or digest mismatch throws and loading is refused.
+ */
+ expectedSha256?: Record<string, string>;
},
): Promise<Agent> {
const sub = opts?.subfolder ?? null;
@@ -553,24 +564,36 @@ export class Agent extends HookRegistry {
let cfg: AgentCfg = {};
let tokenizerJson: unknown | null = null;
let dir = opts?.localDir ?? modelDirOrRepo;
+ let revision: string | null = null;
let provider: SessionProvider;
if (isBrowser) {
const { loadWebBundle, createWebProvider } = await import("./providers.js");
- const bundle = await loadWebBundle(modelDirOrRepo, { subfolder: sub });
+ const bundle = await loadWebBundle(modelDirOrRepo, {
+ subfolder: sub,
+ revision: opts?.revision,
+ expectedSha256: opts?.expectedSha256,
+ });
cfg = bundle.cfg;
tokenizerJson = bundle.tokenizerJson;
dir = bundle.dir;
- provider = await createWebProvider(dir, { numThreads: opts?.numThreads });
+ revision = bundle.revision;
+ provider = await createWebProvider(dir, {
+ numThreads: opts?.numThreads,
+ expectedSha256: opts?.expectedSha256,
+ });
} else {
const { loadNodeBundle, createNodeProvider } = await import("./providers.js");
const bundle = await loadNodeBundle(modelDirOrRepo, {
subfolder: sub,
localDir: opts?.localDir,
token: opts?.token,
+ revision: opts?.revision,
+ expectedSha256: opts?.expectedSha256,
});
cfg = bundle.cfg;
tokenizerJson = bundle.tokenizerJson;
dir = bundle.dir;
+ revision = bundle.revision;
provider = await createNodeProvider(dir, { device: opts?.device, numThreads: opts?.numThreads });
}
if (!tokenizerJson) {
@@ -588,6 +611,6 @@ export class Agent extends HookRegistry {
`Incompatible model: tokenizer.json is missing or invalid in ${JSON.stringify(dir)}: ${String(error)}`,
);
}
- return new Agent({ provider, tok, cfg, lang_temperatures: opts?.lang_temperatures });
+ return new Agent({ provider, tok, cfg, revision, lang_temperatures: opts?.lang_temperatures });
}
}
diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.ts
index 80bd718e..38e105a3 100644
--- a/laya-ts/src/index.ts
+++ b/laya-ts/src/index.ts
@@ -13,7 +13,7 @@ export type {
AgentOptions,
PredictOptions,
} from "./agent.js";
-export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle } from "./providers.js";
+export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle, PINNED_REVISIONS, resolveRevision } from "./providers.js";
export type { Batch, SessionProvider, ProviderOptions, NodeBundle, WebBundle } from "./providers.js";
export { Router, normaliseName, DEFAULT_MODELS } from "./router.js";
export type { RoutedResult, RouteDecision, ModelName, ModelSpec } from "./router.js";
diff --git a/laya-ts/src/providers.ts b/laya-ts/src/providers.ts
index 01670908..5d6916a1 100644
--- a/laya-ts/src/providers.ts
+++ b/laya-ts/src/providers.ts
@@ -1,6 +1,57 @@
/** ONNX session shim: Node (onnxruntime-node) + browser (onnxruntime-web).
* Lazy imports only — unit tests with a fake provider never touch onnxruntime. */
+/** Reviewed commit SHAs of the published checkpoints (mirror of laya/revisions.py).
+ * Loads of these repos pin to the reviewed revision instead of mutable `main`; bump a
+ * pin only after the new revision has been reviewed. */
+export const PINNED_REVISIONS: Record<string, string> = {
+ "convaiinnovations/laya": "55cf4c4ebb4ebe31b2550e8bdf3bd21b99753851",
+ "convaiinnovations/laya-multilingual": "e4e9ddf21a7b1903b7acffd8814ad4307bf63a67",
+ "convaiinnovations/laya-typed-decisions": "1a793eb568e6718f15941d08f85432581df534e3",
+};
+
+/** Explicit `revision` wins; published repos fall back to their reviewed pin; anything
+ * else keeps the hub default (`main`). */
+export function resolveRevision(repoOrId: string, revision?: string | null): string | null {
+ if (revision) return revision;
+ return PINNED_REVISIONS[repoOrId] ?? null;
+}
+
+/** SHA-256 hex via Web Crypto (browsers and modern Node expose globalThis.crypto). */
+async function sha256Hex(data: ArrayBuffer | Uint8Array): Promise<string> {
+ const subtle = (globalThis as { crypto?: { subtle?: any } }).crypto?.subtle;
+ if (!subtle) {
+ throw new Error("laya-ts: SHA-256 verification requires Web Crypto (globalThis.crypto.subtle)");
+ }
+ const digest = await subtle.digest("SHA-256", data);
+ return Array.from(new Uint8Array(digest as ArrayBuffer), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Reject absolute or escaping digest paths before they ever reach the filesystem. */
+function normaliseDigestPath(rel: string): string {
+ const norm = String(rel).replace(/\\/g, "/").replace(/^\/+/, "");
+ if (!norm || norm === ".." || norm.startsWith("../") || norm.includes("/../")) {
+ throw new Error(`laya-ts: unsafe path in expectedSha256: ${JSON.stringify(rel)}`);
+ }
+ return norm;
+}
+
+/** Verify `data` against expectedSha256[rel]; artifacts not listed are left unchecked. */
+async function expectDigest(
+ rel: string,
+ data: ArrayBuffer | Uint8Array,
+ expected: Record<string, string>,
+): Promise<void> {
+ const want = expected[rel] ?? expected[normaliseDigestPath(rel)];
+ if (want === undefined) return;
+ const got = await sha256Hex(data);
+ if (got.toLowerCase() !== String(want).trim().toLowerCase()) {
+ throw new Error(
+ `laya-ts: SHA-256 mismatch for ${rel}: expected ${want}, got ${got}. Refusing to load the artifact.`,
+ );
+ }
+}
+
export interface Batch {
inputIds: number[][];
attentionMask: number[][];
@@ -83,6 +134,8 @@ function pickOutput(out: Record<string, any>, names: string[]): any {
export interface ProviderOptions {
device?: string;
numThreads?: number;
+ /** Opt-in {artifact name: SHA-256 hexdigest} check for fetched ONNX files (web). */
+ expectedSha256?: Record<string, string>;
}
function applyNumThreads(ort: any, numThreads?: number): void {
@@ -159,31 +212,39 @@ async function fetchArrayBuffer(url: string): Promise<ArrayBuffer> {
return await res.arrayBuffer();
}
-async function fetchJson(url: string): Promise<unknown> {
- const buf = await fetchArrayBuffer(url);
- return JSON.parse(new TextDecoder().decode(buf));
-}
-
export interface NodeBundle {
dir: string;
cfg: any;
tokenizerJson: unknown | null;
+ /** Commit SHA the artifacts came from (pinned/requested, or the hub's `x-repo-commit`); null for local dirs. */
+ revision: string | null;
}
export async function loadNodeBundle(
modelDirOrRepo: string,
- opts?: { subfolder?: string | null; localDir?: string; token?: string | null },
+ opts?: {
+ subfolder?: string | null;
+ localDir?: string;
+ token?: string | null;
+ revision?: string | null;
+ expectedSha256?: Record<string, string>;
+ },
): Promise<NodeBundle> {
const fs: typeof import("node:fs/promises") = await import("node:fs/promises");
const path: typeof import("node:path") = await import("node:path");
const os: typeof import("node:os") = await import("node:os");
const sub = opts?.subfolder ?? null;
let dir = opts?.localDir ?? modelDirOrRepo;
+ let resolvedRevision: string | null = null;
try {
const st = await fs.stat(sub ? path.join(dir, sub) : dir);
if (st.isDirectory()) dir = sub ? path.join(dir, sub) : dir;
else dir = path.dirname(dir);
} catch {
+ // Pin published repos to their reviewed commit SHA instead of mutable `main`; the
+ // revision joins the cache key so differently-pinned artifacts never collide.
+ const revision = resolveRevision(modelDirOrRepo, opts?.revision);
+ resolvedRevision = revision;
const cache = path.join(
os.homedir(),
".cache",
@@ -191,6 +252,7 @@ export async function loadNodeBundle(
"hf",
modelDirOrRepo.replace(/\//g, "__"),
sub ?? "root",
+ ...(revision && revision !== "main" ? [revision] : []),
);
await fs.mkdir(cache, { recursive: true });
const token =
@@ -199,8 +261,10 @@ export async function loadNodeBundle(
try {
await fs.stat(path.join(cache, f));
} catch {
- const url = `https://huggingface.co/${modelDirOrRepo}/resolve/main/${sub ? sub + "/" : ""}${f}`;
+ const url = `https://huggingface.co/${modelDirOrRepo}/resolve/${revision ?? "main"}/${sub ? sub + "/" : ""}${f}`;
const res = await fetch(url, token ? { headers: { Authorization: `Bearer ${token}` } } : undefined);
+ const commit = res.headers?.get?.("x-repo-commit");
+ if (commit) resolvedRevision = commit;
if (!res.ok) {
if (f === "rl_agent_config.json") {
throw new Error(
@@ -211,11 +275,35 @@ export async function loadNodeBundle(
}
const target = path.join(cache, f);
await fs.mkdir(path.dirname(target), { recursive: true });
- await fs.writeFile(target, new Uint8Array(await res.arrayBuffer()));
+ // Write-then-rename so an interrupted download never leaves a truncated
+ // artifact that later loads treat as complete.
+ const tmp = `${target}.tmp-${typeof process !== "undefined" ? process.pid : 0}`;
+ await fs.writeFile(tmp, new Uint8Array(await res.arrayBuffer()));
+ await fs.rename(tmp, target);
}
}
dir = cache;
}
+ // Opt-in integrity check over the resolved directory (covers local dirs, warm cache,
+ // and fresh downloads alike) before any artifact is parsed or executed.
+ if (opts?.expectedSha256) {
+ const { createHash } = await import("node:crypto");
+ for (const [rel, want] of Object.entries(opts.expectedSha256)) {
+ const norm = normaliseDigestPath(rel);
+ let buf: Uint8Array;
+ try {
+ buf = new Uint8Array(await fs.readFile(path.join(dir, norm)));
+ } catch {
+ throw new Error(`laya-ts: cannot verify ${JSON.stringify(rel)}: not found under ${dir}`);
+ }
+ const got = createHash("sha256").update(buf).digest("hex");
+ if (got.toLowerCase() !== String(want).trim().toLowerCase()) {
+ throw new Error(
+ `laya-ts: SHA-256 mismatch for ${rel}: expected ${want}, got ${got}. Refusing to load the artifact.`,
+ );
+ }
+ }
+ }
let cfg: any = {};
try {
cfg = JSON.parse(await fs.readFile(path.join(dir, "rl_agent_config.json"), "utf8"));
@@ -233,44 +321,58 @@ export async function loadNodeBundle(
// Try the next supported Hugging Face layout.
}
}
- return { dir, cfg, tokenizerJson };
+ return { dir, cfg, tokenizerJson, revision: resolvedRevision };
}
export interface WebBundle {
dir: string;
cfg: any;
tokenizerJson: unknown | null;
+ /** Pinned/requested commit SHA, if any (full-URL sources have no implicit revision). */
+ revision: string | null;
}
-function baseUrlFor(repoOrUrl: string, subfolder?: string | null): string {
+function baseUrlFor(repoOrUrl: string, subfolder?: string | null, revision?: string | null): string {
const sub = subfolder ? `/${subfolder.replace(/^\/+|\/+$/g, "")}` : "";
if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(repoOrUrl)) {
return `${repoOrUrl.replace(/\/+$/, "")}${sub}`;
}
- return `https://huggingface.co/${repoOrUrl}/resolve/main${sub}`;
+ return `https://huggingface.co/${repoOrUrl}/resolve/${revision ?? "main"}${sub}`;
}
export async function loadWebBundle(
repoOrUrl: string,
- opts?: { subfolder?: string | null },
+ opts?: {
+ subfolder?: string | null;
+ revision?: string | null;
+ expectedSha256?: Record<string, string>;
+ },
): Promise<WebBundle> {
- const base = baseUrlFor(repoOrUrl, opts?.subfolder ?? null);
+ const revision = resolveRevision(repoOrUrl, opts?.revision);
+ const base = baseUrlFor(repoOrUrl, opts?.subfolder ?? null, revision);
+ const fetchVerifiedJson = async (rel: string): Promise<unknown> => {
+ const buf = await fetchArrayBuffer(`${base}/${rel}`);
+ if (opts?.expectedSha256) await expectDigest(rel, buf, opts.expectedSha256);
+ return JSON.parse(new TextDecoder().decode(buf));
+ };
let cfg: any;
try {
- cfg = await fetchJson(`${base}/rl_agent_config.json`);
- } catch {
+ cfg = await fetchVerifiedJson("rl_agent_config.json");
+ } catch (e) {
+ if (e instanceof Error && e.message.startsWith("laya-ts: SHA-256 mismatch")) throw e;
throw new Error(`Incompatible model: ${JSON.stringify(repoOrUrl)} does not contain 'rl_agent_config.json'.`);
}
let tokenizerJson: unknown | null = null;
for (const candidate of ["tokenizer.json", "tokenizer/tokenizer.json"]) {
try {
- tokenizerJson = await fetchJson(`${base}/${candidate}`);
+ tokenizerJson = await fetchVerifiedJson(candidate);
break;
- } catch {
+ } catch (e) {
+ if (e instanceof Error && e.message.startsWith("laya-ts: SHA-256 mismatch")) throw e;
// Try the next supported Hugging Face layout.
}
}
- return { dir: base, cfg, tokenizerJson };
+ return { dir: base, cfg, tokenizerJson, revision };
}
export async function createNodeProvider(
@@ -390,6 +492,11 @@ export async function createWebProvider(
} catch {
throw new Error(`Incompatible model: 'head.onnx' not found (expected ${headUrl}).`);
}
+ // Verify before the bytes reach the runtime: a tampered ONNX never becomes a session.
+ if (opts?.expectedSha256) {
+ await expectDigest("encoder.onnx", encBuf, opts.expectedSha256);
+ await expectDigest("head.onnx", headBuf, opts.expectedSha256);
+ }
let enc: any;
try {
enc = await ort.InferenceSession.create(new Uint8Array(encBuf), {
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index 6153103e..cd7efdd2 100644
--- a/laya-ts/src/router.ts
+++ b/laya-ts/src/router.ts
@@ -120,6 +120,8 @@ export interface RouterOptions {
langGuess?: LangGuess;
lang_guess?: LangGuess;
loader?: AgentLoader;
+ /** Optional hub revision (commit SHA/branch/tag) applied to every checkpoint load. */
+ revision?: string | null;
hooks?: HookArg;
onPredictStart?: PredictHook;
onPredictEnd?: PredictHook;
@@ -154,6 +156,7 @@ export class Router extends HookRegistry {
models: Record<string, ModelSpec>;
device: string | null;
token: string | null | undefined;
+ revision: string | null;
maxLoaded: number;
default: ModelName;
autoTaskDetection: boolean;
@@ -179,6 +182,9 @@ export class Router extends HookRegistry {
}
this.device = opts.device ?? null;
this.token = opts.token ?? (typeof process !== "undefined" ? process.env?.["HF_TOKEN"] : undefined);
+ // Optional hub revision applied to every checkpoint load; published checkpoints pin
+ // to a reviewed SHA even without it (see PINNED_REVISIONS in providers.ts).
+ this.revision = opts.revision ?? null;
this.maxLoaded = Math.max(1, Math.trunc(Number(opts.maxLoaded ?? opts.max_loaded ?? 2)));
this.default = normaliseName(opts.default ?? "english");
this.autoTaskDetection = Boolean(opts.autoTaskDetection ?? opts.auto_task_detection ?? false);
@@ -209,6 +215,7 @@ export class Router extends HookRegistry {
subfolder: spec.subfolder,
device: this.device ?? undefined,
token: this.token ?? undefined,
+ revision: this.revision ?? undefined,
});
}
this._agents.set(key, agent);
diff --git a/laya-ts/tests/revision-pinning.test.ts b/laya-ts/tests/revision-pinning.test.ts
new file mode 100644
index 00000000..90188ca7
--- /dev/null
+++ b/laya-ts/tests/revision-pinning.test.ts
@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Agent } from "../src/agent.js";
+import { Router } from "../src/router.js";
+import { PINNED_REVISIONS, loadNodeBundle, resolveRevision } from "../src/providers.js";
+
+const fakeProvider = () => ({
+ async runEncoder(_b: any) { return { lastHidden: [[1, 0], [0, 1]] }; },
+ async runHead(_h: any) { return { logits: [[2, 0]], act: [[3, 0]] }; },
+});
+
+class StubResponse {
+ constructor(public body: Uint8Array | null, public status = 200) {}
+ get ok() { return this.status >= 200 && this.status < 300; }
+ headers = { get: (n: string) => (n === "x-repo-commit" ? "abc123" : null) };
+ async arrayBuffer() { return (this.body ?? new Uint8Array()).buffer as ArrayBuffer; }
+}
+
+const tmpDirs: string[] = [];
+function makeCheckpoint(files: Record<string, Uint8Array>): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "laya-rev-"));
+ tmpDirs.push(dir);
+ for (const [rel, data] of Object.entries(files)) {
+ const p = path.join(dir, rel);
+ fs.mkdirSync(path.dirname(p), { recursive: true });
+ fs.writeFileSync(p, data);
+ }
+ return dir;
+}
+const cfgFile = { "rl_agent_config.json": new TextEncoder().encode('{"act_costs":{"a":0}}') };
+const sha256 = (b: Uint8Array) => createHash("sha256").update(b).digest("hex");
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ for (const d of tmpDirs.splice(0)) fs.rmSync(d, { recursive: true, force: true });
+});
+
+describe("resolveRevision", () => {
+ it("explicit revision wins over the pin", () => {
+ expect(resolveRevision("convaiinnovations/laya", "abc123")).toBe("abc123");
+ });
+ it("published repos fall back to the reviewed pin", () => {
+ for (const [repo, sha] of Object.entries(PINNED_REVISIONS)) {
+ expect(sha).toMatch(/^[0-9a-f]{40}$/);
+ expect(resolveRevision(repo)).toBe(sha);
+ }
+ });
+ it("unknown repos keep the hub default", () => {
+ expect(resolveRevision("acme/custom-model")).toBeNull();
+ });
+});
+
+describe("loadNodeBundle pinning", () => {
+ it("fetches published checkpoints at the pinned revision and joins it to the cache key", async () => {
+ const urls: string[] = [];
+ vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+ urls.push(url);
+ return url.endsWith("rl_agent_config.json")
+ ? new StubResponse(cfgFile["rl_agent_config.json"])
+ : new StubResponse(null, 404);
+ }));
+ const pin = PINNED_REVISIONS["convaiinnovations/laya"];
+ const cacheDir = path.join(os.homedir(), ".cache", "laya-ts", "hf", "convaiinnovations__laya", "root", pin);
+ try {
+ const bundle = await loadNodeBundle("convaiinnovations/laya");
+ expect(urls[0]).toContain(`/resolve/${pin}/`);
+ expect(bundle.dir).toBe(cacheDir);
+ // The hub reports the exact commit served; that wins over the requested pin.
+ expect(bundle.revision).toBe("abc123");
+ expect(bundle.cfg.act_costs).toEqual({ a: 0 });
+ } finally {
+ fs.rmSync(path.join(os.homedir(), ".cache", "laya-ts", "hf", "convaiinnovations__laya"), { recursive: true, force: true });
+ }
+ });
+
+ it("unpinned repos keep the mutable main default", async () => {
+ const urls: string[] = [];
+ vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+ urls.push(url);
+ return url.endsWith("rl_agent_config.json")
+ ? new StubResponse(cfgFile["rl_agent_config.json"])
+ : new StubResponse(null, 404);
+ }));
+ try {
+ await loadNodeBundle("acme/custom-model");
+ expect(urls[0]).toContain("/resolve/main/");
+ } finally {
+ fs.rmSync(path.join(os.homedir(), ".cache", "laya-ts", "hf", "acme__custom-model"), { recursive: true, force: true });
+ }
+ });
+});
+
+describe("loadNodeBundle expectedSha256", () => {
+ it("local dirs never download and report no revision", async () => {
+ const fetchSpy = vi.fn();
+ vi.stubGlobal("fetch", fetchSpy);
+ const dir = makeCheckpoint(cfgFile);
+ const bundle = await loadNodeBundle(dir);
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(bundle.revision).toBeNull();
+ });
+
+ it("matching digests pass; unlisted artifacts are unchecked", async () => {
+ const weights = new TextEncoder().encode("weights");
+ const dir = makeCheckpoint({ ...cfgFile, "model.bin": weights });
+ const bundle = await loadNodeBundle(dir, {
+ expectedSha256: { "model.bin": sha256(weights) },
+ });
+ expect(bundle.dir).toBe(dir);
+ });
+
+ it("mismatches refuse to load", async () => {
+ const dir = makeCheckpoint({ ...cfgFile, "model.bin": new TextEncoder().encode("weights") });
+ await expect(loadNodeBundle(dir, { expectedSha256: { "model.bin": "0".repeat(64) } }))
+ .rejects.toThrow(/SHA-256 mismatch/);
+ });
+
+ it("missing artifacts refuse to load", async () => {
+ const dir = makeCheckpoint(cfgFile);
+ await expect(loadNodeBundle(dir, { expectedSha256: { "absent.bin": "0".repeat(64) } }))
+ .rejects.toThrow(/cannot verify/);
+ });
+
+ it("escaping digest paths are rejected", async () => {
+ const dir = makeCheckpoint(cfgFile);
+ for (const rel of ["../evil", "..", "a/../../evil"]) {
+ await expect(loadNodeBundle(dir, { expectedSha256: { [rel]: "0".repeat(64) } }))
+ .rejects.toThrow(/unsafe path/);
+ }
+ });
+});
+
+describe("revision plumbing", () => {
+ it("Agent keeps the revision from its options", () => {
+ const agent = new Agent({ provider: fakeProvider(), cfg: {}, revision: "abc123" });
+ expect(agent.revision).toBe("abc123");
+ expect(new Agent({ provider: fakeProvider(), cfg: {} }).revision).toBeNull();
+ });
+
+ it("Router stores an explicit revision", () => {
+ expect(new Router({ revision: "abc123" }).revision).toBe("abc123");
+ expect(new Router().revision).toBeNull();
+ });
+});
diff --git a/laya/agent.py b/laya/agent.py
index a76041f7..c16f7169 100644
--- a/laya/agent.py
+++ b/laya/agent.py
@@ -28,6 +28,7 @@ from .common import (
temp_bucket,
)
from .hooks import HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks
+from .revisions import resolve_revision, snapshot_revision, verify_digests
def _fix_tokenizer_config(path: str):
@@ -216,6 +217,8 @@ class Agent(HookRegistry):
subfolder: Optional[str] = None,
fast: bool = False,
compile: bool = False,
+ revision: Optional[str] = None,
+ expected_sha256: Optional[Dict[str, str]] = None,
lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
hooks=None,
on_predict_start=None,
@@ -225,6 +228,14 @@ class Agent(HookRegistry):
):
"""Load a Laya checkpoint.
+ `revision` pins the Hub download to an explicit commit SHA/branch/tag. The
+ published convaiinnovations/* checkpoints default to the reviewed SHA pinned in
+ `laya.revisions.PINNED_REVISIONS` instead of mutable `main`; pass `revision` to
+ override. `expected_sha256` ({path relative to the checkpoint dir: hexdigest})
+ verifies artifact integrity before any weight is parsed or executed; it is opt-in
+ and applies to local directories too. A missing artifact or digest mismatch raises
+ `ValueError` and loading is refused.
+
`fast=True` swaps the encoder/head forward for the TileLang fast path (CUDA only, needs
`pip install laya[fast]`); see `Agent.accelerate`.
@@ -250,6 +261,7 @@ class Agent(HookRegistry):
from transformers.modeling_utils import no_init_weights
model_dir = model_id_or_path
+ self.revision: Optional[str] = None
if not os.path.exists(model_dir):
if model_id_or_path.startswith(("/", "./", "../")) or os.path.isabs(model_id_or_path):
raise FileNotFoundError(
@@ -260,6 +272,7 @@ class Agent(HookRegistry):
# Restrict root checkpoints too: the default repo also contains sibling
# checkpoints, which an unfiltered snapshot would unnecessarily download.
+ revision = resolve_revision(model_id_or_path, revision)
prefix = f"{subfolder}/" if subfolder else ""
kw = {
"token": token or os.environ.get("HF_TOKEN") or None,
@@ -267,7 +280,11 @@ class Agent(HookRegistry):
"rl_agent_config.json", "model.safetensors", "tokenizer/*", "encoder/*",
)],
}
+ if revision:
+ kw["revision"] = revision
model_dir = snapshot_download(model_id_or_path, **kw)
+ # The cache layout records which commit the snapshot points at.
+ self.revision = snapshot_revision(model_dir) or revision
if subfolder:
model_dir = os.path.join(model_dir, subfolder)
@@ -276,6 +293,10 @@ class Agent(HookRegistry):
f"Subfolder {subfolder!r} not found in {model_id_or_path!r}."
)
+ # Verify integrity before any file in the checkpoint is parsed or executed.
+ if expected_sha256:
+ verify_digests(model_dir, expected_sha256)
+
_fix_tokenizer_config(model_dir)
cfg_path = os.path.join(model_dir, "rl_agent_config.json")
@@ -920,6 +941,7 @@ RLAgent = Agent
def load(model_id_or_path: str = "convaiinnovations/laya", device: Optional[str] = None,
token: Optional[str] = None, subfolder: Optional[str] = None, fast: bool = False,
+ revision: Optional[str] = None, expected_sha256: Optional[Dict[str, str]] = None,
lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
hooks=None, on_predict_start=None, on_predict_end=None,
hooks_raise: bool = True, hooks_concurrent: bool = True) -> Agent:
@@ -931,10 +953,12 @@ def load(model_id_or_path: str = "convaiinnovations/laya", device: Optional[str]
laya.load("convaiinnovations/laya", subfolder="multilingual")
laya.load("convaiinnovations/laya", fast=True) # TileLang GPU fast path
+ `revision`/`expected_sha256` pin and verify the downloaded artifacts; see `Agent`.
`hooks` / `on_predict_start` / `on_predict_end` observe or shape every prediction; see
`laya.hooks`.
"""
return Agent(model_id_or_path, device=device, token=token, subfolder=subfolder, fast=fast,
+ revision=revision, expected_sha256=expected_sha256,
lang_temperatures=lang_temperatures,
hooks=hooks, on_predict_start=on_predict_start, on_predict_end=on_predict_end,
hooks_raise=hooks_raise, hooks_concurrent=hooks_concurrent)
diff --git a/laya/common.py b/laya/common.py
index 683b8a45..aac9507f 100644
--- a/laya/common.py
+++ b/laya/common.py
@@ -206,7 +206,8 @@ def _apply_rope_config(ecfg) -> None:
setattr(ecfg, attr, float(theta))
-def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool = True) -> DecisionModel:
+def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool = True,
+ revision: Optional[str] = None) -> DecisionModel:
from transformers import AutoConfig, AutoModel
if not pretrained or (encoder_dir and os.path.exists(encoder_dir)):
@@ -214,7 +215,11 @@ def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool =
_apply_rope_config(ecfg)
enc = AutoModel.from_config(ecfg, attn_implementation="sdpa")
else:
- enc = AutoModel.from_pretrained(cfg["encoder"], attn_implementation="sdpa")
+ # Training-time Hub load of the base encoder; allow pinning it like the checkpoints.
+ kw = {"attn_implementation": "sdpa"}
+ if revision:
+ kw["revision"] = revision
+ enc = AutoModel.from_pretrained(cfg["encoder"], **kw)
return DecisionModel(enc, cfg.get("head_layers", 2), len(cfg.get("act_costs", {})) + 1)
diff --git a/laya/onnx_agent.py b/laya/onnx_agent.py
index 52326404..986076d0 100644
--- a/laya/onnx_agent.py
+++ b/laya/onnx_agent.py
@@ -8,6 +8,7 @@ from typing import Any, Dict, Optional, Union
import numpy as np
from laya.hooks import HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks
+from laya.revisions import resolve_revision, snapshot_revision, verify_digests
from laya.common import (
QTYPES,
answer_confidence,
@@ -38,6 +39,8 @@ class ONNXAgent(HookRegistry):
model_id_or_path: str,
onnx_path: str = "laya.onnx",
subfolder: Optional[str] = None,
+ revision: Optional[str] = None,
+ expected_sha256: Optional[Dict[str, str]] = None,
hooks=None,
on_predict_start=None,
on_predict_end=None,
@@ -51,6 +54,13 @@ class ONNXAgent(HookRegistry):
(used to load the tokenizer and config).
onnx_path: Path to the exported .onnx file.
subfolder: Optional subfolder if downloading from a repo bundle.
+ revision: Optional Hub revision (commit SHA/branch/tag). Published
+ convaiinnovations/* checkpoints default to the reviewed SHA pinned
+ in `laya.revisions.PINNED_REVISIONS` instead of mutable `main`.
+ expected_sha256: Optional {path relative to the checkpoint dir: hexdigest}
+ verified before any checkpoint file is parsed; opt-in, and applies
+ to local directories too. A missing artifact or digest mismatch
+ raises `ValueError` and loading is refused.
hooks (HookArg): Opt-in prediction hooks; see `laya.hooks`.
on_predict_start (PredictHookArg): An opt-in start hook, run before inference.
on_predict_end (PredictHookArg): An opt-in end hook, run after inference.
@@ -68,6 +78,7 @@ class ONNXAgent(HookRegistry):
from transformers import AutoTokenizer
model_dir = model_id_or_path
+ self.revision: Optional[str] = None
if not os.path.exists(model_dir):
if model_id_or_path.startswith(("/", "./", "../")) or os.path.isabs(model_id_or_path):
raise FileNotFoundError(
@@ -75,13 +86,17 @@ class ONNXAgent(HookRegistry):
)
from huggingface_hub import snapshot_download
+ revision = resolve_revision(model_id_or_path, revision)
prefix = f"{subfolder}/" if subfolder else ""
kw = {
"allow_patterns": [prefix + name for name in (
"rl_agent_config.json", "tokenizer/*", "encoder/*",
)],
}
+ if revision:
+ kw["revision"] = revision
model_dir = snapshot_download(model_id_or_path, **kw)
+ self.revision = snapshot_revision(model_dir) or revision
if subfolder:
model_dir = os.path.join(model_dir, subfolder)
@@ -90,6 +105,10 @@ class ONNXAgent(HookRegistry):
f"Subfolder {subfolder!r} not found in {model_id_or_path!r}."
)
+ # Verify integrity before any file in the checkpoint is parsed or executed.
+ if expected_sha256:
+ verify_digests(model_dir, expected_sha256)
+
cfg_path = os.path.join(model_dir, "rl_agent_config.json")
if not os.path.exists(cfg_path):
raise FileNotFoundError(
diff --git a/laya/revisions.py b/laya/revisions.py
new file mode 100644
index 00000000..58863440
--- /dev/null
+++ b/laya/revisions.py
@@ -0,0 +1,71 @@
+"""Supply-chain integrity for published checkpoints: pinned revisions and digest checks.
+
+Runtime loaders default to the mutable ``main`` revision of a Hub repo. For the published
+checkpoints that is a silent-behavior-change risk: a compromised or accidentally changed
+model repository would change routing, confidence, guardrail, and ONNX behavior with no
+code change on the user's side. Loading a published repo without an explicit revision
+therefore pins to the reviewed commit SHA below, and any loader accepts an optional
+SHA-256 map to verify artifact integrity before weights reach the runtime.
+"""
+import hashlib
+import os
+from typing import Dict, Optional
+
+# Reviewed commit SHAs of the published checkpoints. Bump a pin only after the new
+# revision has been reviewed; treat an unexpected upstream SHA change as a prompt to
+# review, not to blindly re-pin.
+PINNED_REVISIONS: Dict[str, str] = {
+ "convaiinnovations/laya": "55cf4c4ebb4ebe31b2550e8bdf3bd21b99753851",
+ "convaiinnovations/laya-multilingual": "e4e9ddf21a7b1903b7acffd8814ad4307bf63a67",
+ "convaiinnovations/laya-typed-decisions": "1a793eb568e6718f15941d08f85432581df534e3",
+}
+
+
+def resolve_revision(model_id_or_path: str, revision: Optional[str] = None) -> Optional[str]:
+ """Pick the revision to download.
+
+ An explicit `revision` always wins; a published repo falls back to its reviewed pin;
+ anything else returns None so the Hub default (`main`) applies unchanged.
+ """
+ if revision:
+ return revision
+ return PINNED_REVISIONS.get(model_id_or_path)
+
+
+def snapshot_revision(path: str) -> Optional[str]:
+ """Commit SHA a Hub snapshot directory points at, or None for a plain directory.
+
+ `snapshot_download` returns ``<cache>/snapshots/<sha>``; resolving symlinks keeps this
+ correct when the snapshot entry is a link into the blob store.
+ """
+ real = os.path.realpath(path).rstrip(os.sep)
+ parent, base = os.path.split(real)
+ if os.path.basename(parent) == "snapshots" and base:
+ return base
+ return None
+
+
+def verify_digests(model_dir: str, expected: Dict[str, str]) -> None:
+ """Verify SHA-256 digests of files under `model_dir` against {relpath: hexdigest}.
+
+ Raises FileNotFoundError when a listed file is absent and ValueError on a digest
+ mismatch or an unsafe (absolute or escaping) relative path. Verification runs before
+ any weight is parsed or executed, so a tampered artifact never reaches the runtime.
+ """
+ for rel, want in expected.items():
+ rel_norm = str(rel).replace("\\", "/").lstrip("/")
+ if not rel_norm or rel_norm == ".." or rel_norm.startswith("../") or "/../" in rel_norm:
+ raise ValueError("laya: unsafe path in expected digests: %r" % (rel,))
+ path = os.path.join(model_dir, rel_norm)
+ if not os.path.isfile(path):
+ raise FileNotFoundError(
+ "laya: cannot verify %r: no such file under %s" % (rel, model_dir))
+ digest = hashlib.sha256()
+ with open(path, "rb") as f:
+ for chunk in iter(lambda: f.read(1 << 20), b""):
+ digest.update(chunk)
+ got = digest.hexdigest()
+ if got.lower() != str(want).strip().lower():
+ raise ValueError(
+ "laya: SHA-256 mismatch for %s: expected %s, got %s. The artifact does "
+ "not match the reviewed digest; refusing to load it." % (rel, want, got))
diff --git a/laya/router.py b/laya/router.py
index 91920c08..556bbfd8 100644
--- a/laya/router.py
+++ b/laya/router.py
@@ -214,6 +214,7 @@ class Router(HookRegistry):
models: Optional[Dict[str, str]] = None,
device: Optional[str] = None,
token: Optional[str] = None,
+ revision: Optional[str] = None,
max_loaded: int = 2,
default: str = "english",
auto_task_detection: bool = False,
@@ -236,6 +237,10 @@ class Router(HookRegistry):
self.models.update({normalise_name(k): v for k, v in models.items()})
self.device = device
self.token = token or os.environ.get("HF_TOKEN")
+ # Optional Hub revision (commit SHA/branch/tag) applied to every checkpoint load.
+ # The published checkpoints pin to a reviewed SHA even without this; see
+ # `laya.revisions.PINNED_REVISIONS`.
+ self.revision = revision
self.max_loaded = max(1, int(max_loaded))
self.default = normalise_name(default)
self.auto_task_detection = bool(auto_task_detection)
@@ -267,7 +272,8 @@ class Router(HookRegistry):
return self._agents[key]
from .agent import Agent
repo, sub = _split(self.models[key])
- agent = Agent(repo, device=self.device, token=self.token, subfolder=sub)
+ agent = Agent(repo, device=self.device, token=self.token, subfolder=sub,
+ revision=self.revision)
self._agents[key] = agent
self._order.append(key)
evicted = self._evict_locked()
@@ -381,6 +387,12 @@ class Router(HookRegistry):
with self._lock:
return list(self._order)
+ @property
+ def loaded_revisions(self) -> Dict[str, Optional[str]]:
+ """Commit SHA each resident agent was loaded from (None for local paths)."""
+ with self._lock:
+ return {name: getattr(agent, "revision", None) for name, agent in self._agents.items()}
+
def _resolve_hint(self, hint: Any, state: Union[str, dict, list, None]) -> Optional[bool]:
"""True/False for a hint about whether the English checkpoint can read `state`.
diff --git a/laya/serve.py b/laya/serve.py
index afecb966..8e73a93d 100644
--- a/laya/serve.py
+++ b/laya/serve.py
@@ -242,6 +242,7 @@ def create_app(router: Optional[Any] = None):
return {
"status": "ok",
"loaded": router.loaded,
+ "revisions": router.loaded_revisions,
"device": os.environ.get("LAYA_DEVICE") or "auto",
}
diff --git a/tests/test_revision_pinning.py b/tests/test_revision_pinning.py
new file mode 100644
index 00000000..a0f8b55f
--- /dev/null
+++ b/tests/test_revision_pinning.py
@@ -0,0 +1,142 @@
+"""Revision pinning and digest verification tests; no network required.
+
+Run: python tests/test_revision_pinning.py
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from types import SimpleNamespace
+from unittest.mock import patch
+
+os.environ.setdefault("USE_TF", "0")
+os.environ.setdefault("USE_TORCH", "1")
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from laya.agent import Agent # noqa: E402
+from laya.revisions import ( # noqa: E402
+ PINNED_REVISIONS,
+ resolve_revision,
+ snapshot_revision,
+ verify_digests,
+)
+from laya.router import Router # noqa: E402
+
+
+class _StopLoad(Exception):
+ """Sentinel raised by the fake snapshot_download once kwargs are captured."""
+
+
+def _capturing_snapshot(captured):
+ def fake_snapshot(repo_id, **kwargs):
+ captured.update(kwargs)
+ raise _StopLoad
+ return fake_snapshot
+
+
+class ResolveRevisionTests(unittest.TestCase):
+ def test_explicit_revision_wins(self):
+ self.assertEqual(resolve_revision("convaiinnovations/laya", "abc123"), "abc123")
+
+ def test_published_repos_fall_back_to_the_pin(self):
+ for repo, sha in PINNED_REVISIONS.items():
+ self.assertEqual(resolve_revision(repo), sha)
+ self.assertTrue(all(c in "0123456789abcdef" for c in sha), repo)
+ self.assertEqual(len(sha), 40, repo)
+
+ def test_unknown_repo_keeps_the_hub_default(self):
+ self.assertIsNone(resolve_revision("acme/custom-model"))
+ self.assertIsNone(resolve_revision("acme/custom-model", ""))
+
+
+class SnapshotRevisionTests(unittest.TestCase):
+ def test_snapshot_layout(self):
+ self.assertEqual(snapshot_revision("/cache/models--a--b/snapshots/deadbeef"), "deadbeef")
+
+ def test_plain_directory(self):
+ self.assertIsNone(snapshot_revision("/plain/dir"))
+ self.assertIsNone(snapshot_revision(""))
+
+
+class VerifyDigestsTests(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.dir = self.tmp.name
+ with open(os.path.join(self.dir, "weights.bin"), "wb") as f:
+ f.write(b"weights")
+ self.digest = hashlib.sha256(b"weights").hexdigest()
+
+ def tearDown(self):
+ self.tmp.cleanup()
+
+ def test_matching_digest_passes(self):
+ verify_digests(self.dir, {"weights.bin": self.digest})
+ verify_digests(self.dir, {"weights.bin": self.digest.upper()})
+
+ def test_mismatch_raises(self):
+ with self.assertRaises(ValueError):
+ verify_digests(self.dir, {"weights.bin": "0" * 64})
+
+ def test_missing_file_raises(self):
+ with self.assertRaises(FileNotFoundError):
+ verify_digests(self.dir, {"absent.bin": self.digest})
+
+ def test_escaping_paths_rejected(self):
+ for rel in ("../evil", "..", "a/../../evil", "\\..\\evil"):
+ with self.assertRaises(ValueError, msg=rel):
+ verify_digests(self.dir, {rel: self.digest})
+
+
+class AgentPinningTests(unittest.TestCase):
+ def test_hub_load_pins_published_repo(self):
+ captured = {}
+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):
+ with self.assertRaises(_StopLoad):
+ Agent("convaiinnovations/laya")
+ self.assertEqual(captured["revision"], PINNED_REVISIONS["convaiinnovations/laya"])
+
+ def test_explicit_revision_overrides_the_pin(self):
+ captured = {}
+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):
+ with self.assertRaises(_StopLoad):
+ Agent("convaiinnovations/laya", revision="abc123")
+ self.assertEqual(captured["revision"], "abc123")
+
+ def test_unpinned_repo_gets_no_revision_kwarg(self):
+ captured = {}
+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):
+ with self.assertRaises(_StopLoad):
+ Agent("acme/custom-model")
+ self.assertNotIn("revision", captured)
+
+ def test_local_path_never_downloads(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ with patch("huggingface_hub.snapshot_download") as download:
+ with self.assertRaises(FileNotFoundError):
+ Agent(tmp)
+ download.assert_not_called()
+
+ def test_digest_mismatch_raises_before_weights_load(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ (Path(tmp) / "rl_agent_config.json").write_text(json.dumps({"act_costs": {"a": 0}}))
+ (Path(tmp) / "model.safetensors").write_bytes(b"not the reviewed weights")
+ with self.assertRaises(ValueError):
+ Agent(tmp, expected_sha256={"model.safetensors": "0" * 64})
+
+
+class RouterRevisionTests(unittest.TestCase):
+ def test_router_stores_an_explicit_revision(self):
+ self.assertEqual(Router(revision="abc123").revision, "abc123")
+ self.assertIsNone(Router().revision)
+
+ def test_loaded_revisions_reports_resident_agents(self):
+ router = Router()
+ router.attach("english", SimpleNamespace(revision="sha-english"))
+ self.assertEqual(router.loaded_revisions, {"english": "sha-english"})
+
+
+if __name__ == "__main__":
+ unittest.main()