Skip to content

Commit 6c0042a

Browse files
committed
fix(cli): refresh stale catalog vectors
1 parent 4818dd0 commit 6c0042a

15 files changed

Lines changed: 432 additions & 84 deletions

File tree

‎docs/schema/registry.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,19 @@
2121
"format": "uri",
2222
"description": "Registry homepage URL."
2323
},
24+
"catalogArtifact": {
25+
"type": "object",
26+
"description": "Published on-device vector artifact for this registry.",
27+
"required": ["revision"],
28+
"additionalProperties": false,
29+
"properties": {
30+
"revision": {
31+
"type": "string",
32+
"pattern": "^[a-f0-9]{64}$",
33+
"description": "SHA-256 identity of the searchable corpus and embedding contract."
34+
}
35+
}
36+
},
2437
"items": {
2538
"type": "array",
2639
"description": "Items in this registry. Each entry is a shorthand reference; the full item manifest lives at <type-dir>/<name>/registry-item.json.",

‎lefthook.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ pre-commit:
2929
# opt-in they were never asked to install; CI names the gap instead.
3030
run: |
3131
bun scripts/catalog/build-local-vectors.ts || { [ $? -eq 3 ] && exit 0; exit 1; }
32-
git add registry/catalog-artifact/local-vectors.json registry/catalog-artifact/local-vectors.bin
32+
git add registry/registry.json registry/catalog-artifact/local-vectors.json registry/catalog-artifact/local-vectors.bin
3333
typecheck:
3434
glob: "*.{ts,tsx}"
3535
run: cd packages/core && bunx tsc --noEmit && cd ../studio && bunx tsc --noEmit && cd ../.. && bunx tsc --noEmit -p scripts/tsconfig.json

‎packages/cli/src/commands/catalog.test.ts‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ describe("countUnindexed", () => {
7070

7171
const state = vi.hoisted(() => ({
7272
registry: [] as Array<{ name: string; type: string; tags?: string[] }>,
73+
artifactRevision: "revision-current",
74+
cachedVectorRevision: "revision-current",
75+
vectorFetches: 0,
76+
vectorFetchSucceeds: true,
7377
ranking: null as Array<{ name: string; score: number }> | null,
7478
rankingError: null as Error | null,
7579
indexed: [] as string[],
@@ -84,7 +88,6 @@ const state = vi.hoisted(() => ({
8488
}));
8589

8690
vi.mock("../registry/resolver.js", () => ({
87-
listRegistryItems: async () => state.registry,
8891
loadAllItems: async (entries: Array<{ name: string; type: string; tags?: string[] }>) =>
8992
entries.map((entry) => ({
9093
name: entry.name,
@@ -95,6 +98,13 @@ vi.mock("../registry/resolver.js", () => ({
9598
})),
9699
}));
97100

101+
vi.mock("../registry/remote.js", () => ({
102+
fetchRegistryManifest: async () => ({
103+
items: state.registry,
104+
catalogArtifact: { revision: state.artifactRevision },
105+
}),
106+
}));
107+
98108
vi.mock("@clack/prompts", () => ({
99109
confirm: async () => state.confirmAnswer,
100110
isCancel: (value: unknown) => value === null,
@@ -116,6 +126,7 @@ vi.mock("../registry/localModel.js", () => ({
116126
},
117127
ensureLocalModel: async () => {
118128
state.downloads += 1;
129+
if (state.modelStatus === "unavailable") state.modelStatus = "ready";
119130
return true;
120131
},
121132
recordLocalModelConsent: (enabled: boolean) => {
@@ -138,8 +149,15 @@ vi.mock("../registry/localSemantic.js", () => ({
138149
return state.ranking;
139150
},
140151
localVectorNames: () => state.indexed,
152+
cachedLocalVectorRevision: () => state.cachedVectorRevision,
141153
hasLocalVectors: () => true,
142-
fetchLocalVectors: async () => true,
154+
fetchLocalVectors: async (_registry: string, options: { expectedRevision?: string } = {}) => {
155+
state.vectorFetches += 1;
156+
if (state.vectorFetchSucceeds && options.expectedRevision !== undefined) {
157+
state.cachedVectorRevision = options.expectedRevision;
158+
}
159+
return state.vectorFetchSucceeds;
160+
},
143161
}));
144162

145163
const block = (name: string, tags?: string[]): { name: string; type: string; tags?: string[] } => ({
@@ -187,6 +205,10 @@ async function runEnvelope(args: Record<string, unknown>): Promise<Envelope> {
187205

188206
beforeEach(() => {
189207
state.modelStatus = "ready";
208+
state.artifactRevision = "revision-current";
209+
state.cachedVectorRevision = "revision-current";
210+
state.vectorFetches = 0;
211+
state.vectorFetchSucceeds = true;
190212
state.rankingError = null;
191213
state.confirmAnswer = true;
192214
state.consentRecorded = [];
@@ -291,6 +313,40 @@ describe("catalog --json meaning search", () => {
291313
expect(envelope.tier).toBe("words");
292314
expect(envelope.warnings).toEqual(["on-device search did not run: model could not load"]);
293315
});
316+
317+
it("refreshes a changed vector revision under existing consent", async () => {
318+
state.cachedVectorRevision = "revision-previous";
319+
320+
const envelope = await runEnvelope({ query: "count up" });
321+
322+
expect(envelope.tier).toBe("on-device");
323+
expect(state.vectorFetches).toBe(1);
324+
expect(state.cachedVectorRevision).toBe("revision-current");
325+
expect(state.consentRecorded).toEqual([]);
326+
});
327+
328+
it("replaces a changed model revision under existing consent", async () => {
329+
state.modelStatus = "unavailable";
330+
331+
const envelope = await runEnvelope({ query: "count up" });
332+
333+
expect(envelope.tier).toBe("on-device");
334+
expect(state.downloads).toBe(1);
335+
expect(state.consentRecorded).toEqual([]);
336+
});
337+
338+
it("keeps the previous vectors and reports a failed routine refresh", async () => {
339+
state.cachedVectorRevision = "revision-previous";
340+
state.vectorFetchSucceeds = false;
341+
342+
const envelope = await runEnvelope({ query: "count up" });
343+
344+
expect(envelope.tier).toBe("on-device");
345+
expect(state.cachedVectorRevision).toBe("revision-previous");
346+
expect(envelope.warnings).toEqual([
347+
"on-device search is using the previous catalog vectors because the update failed",
348+
]);
349+
});
294350
});
295351

296352
describe("catalog meaning search, on a terminal", () => {

‎packages/cli/src/commands/catalog.ts‎

Lines changed: 63 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ export const examples: Example[] = [
1212
import * as clack from "@clack/prompts";
1313
import { type ItemType } from "@hyperframes/core";
1414
import { c } from "../ui/colors.js";
15-
import { listRegistryItems, loadAllItems } from "../registry/resolver.js";
15+
import { loadAllItems } from "../registry/resolver.js";
16+
import { fetchRegistryManifest } from "../registry/remote.js";
1617
import { loadProjectConfig, DEFAULT_PROJECT_CONFIG } from "../utils/projectConfig.js";
1718
import { resolve } from "node:path";
1819
import { finishCommand } from "../utils/commandResult.js";
@@ -21,12 +22,14 @@ import { searchByWords } from "../registry/localSearch.js";
2122
import {
2223
downloadOfferMessage,
2324
ensureLocalModel,
25+
type LocalModelStatus,
2426
localModelStatus,
2527
nonInteractiveConsentMessage,
2628
recordLocalModelConsent,
2729
} from "../registry/localModel.js";
2830
import { localRuntimeAvailable } from "../registry/localEmbedder.js";
2931
import {
32+
cachedLocalVectorRevision,
3033
fetchLocalVectors,
3134
hasLocalVectors,
3235
localSemanticRanking,
@@ -46,17 +49,19 @@ import {
4649
// fallow-ignore-next-line complexity
4750
async function prepareOnDeviceTier(opts: {
4851
assumedYes: boolean;
52+
artifactRevision?: string;
4953
canPrompt: boolean;
5054
registry: string;
5155
registryNames: ReadonlySet<string>;
56+
status: LocalModelStatus;
5257
}): Promise<string[]> {
5358
const warnings: string[] = [];
5459
const warn = (message: string): void => {
5560
warnings.push(message);
5661
console.error(message);
5762
};
5863

59-
const status = localModelStatus();
64+
const status = opts.status;
6065
if (!opts.assumedYes && status.status === "declined") {
6166
warn(
6267
"on-device search skipped: the model download was previously declined. Re-run with --yes to consent.",
@@ -99,14 +104,14 @@ async function prepareOnDeviceTier(opts: {
99104
recordLocalModelConsent(true);
100105
}
101106
const model = await ensureLocalModel();
102-
// The vectors are fetched once and nothing ever invalidates them, so an index
103-
// that no longer covers the registry is the same situation as one that is not
104-
// there at all: meaning search cannot reach part of the catalog. Both take the
105-
// path this flag already takes. Deciding it costs a local read of the
106-
// artifact's own name list; the only fetch is the one --on-device already
107-
// performs when the vectors are absent.
108-
if (!hasLocalVectors() || countUnindexed(opts.registryNames, localVectorNames()) > 0) {
109-
await fetchLocalVectors(opts.registry);
107+
const revisionStale =
108+
opts.artifactRevision !== undefined && cachedLocalVectorRevision() !== opts.artifactRevision;
109+
if (
110+
!hasLocalVectors() ||
111+
revisionStale ||
112+
countUnindexed(opts.registryNames, localVectorNames()) > 0
113+
) {
114+
await fetchLocalVectors(opts.registry, { expectedRevision: opts.artifactRevision });
110115
}
111116
// Deliberately not the fetch's own answer. A refresh that fails still leaves
112117
// the previous vectors on disk, and those still rank: reporting the tier
@@ -117,6 +122,11 @@ async function prepareOnDeviceTier(opts: {
117122
warn(
118123
`on-device search unavailable: ${!model ? "model" : "catalog vectors"} could not be fetched`,
119124
);
125+
} else if (
126+
opts.artifactRevision !== undefined &&
127+
cachedLocalVectorRevision() !== opts.artifactRevision
128+
) {
129+
warn("on-device search is using the previous catalog vectors because the update failed");
120130
}
121131
return warnings;
122132
}
@@ -178,11 +188,11 @@ export default defineCommand({
178188
finishCommand(1);
179189
}
180190

181-
// Asked for unnarrowed on purpose. `listRegistryItems` filters the same
182-
// in-memory manifest either way, so the whole list costs no extra fetch,
183-
// and its names are the only honest definition of "in this registry" once
184-
// the user's own --type/--tag has narrowed what gets loaded.
185-
const entries = await listRegistryItems(undefined, { baseUrl: config.registry });
191+
// Asked for the whole manifest on purpose: its item list defines coverage,
192+
// and its artifact revision is the one owner of vector freshness.
193+
const manifest = await fetchRegistryManifest(config.registry);
194+
const entries = manifest?.items ?? [];
195+
const artifactRevision = manifest?.catalogArtifact?.revision;
186196
const catalog = entries.filter((e) => e.type !== "hyperframes:example");
187197
const registryNames = new Set(catalog.map((e) => e.name));
188198
const filtered = typeFilter ? catalog.filter((e) => e.type === typeFilter) : catalog;
@@ -204,16 +214,31 @@ export default defineCommand({
204214
// Collected rather than only printed, so --json can carry the same reasons
205215
// the terminal shows. A machine that asked for a tier deserves to be told
206216
// it did not run.
207-
const warnings =
208-
query && args["on-device"] === true
209-
? await prepareOnDeviceTier({
210-
assumedYes: args.yes === true,
211-
canPrompt: process.stdout.isTTY === true && !json,
212-
registry: config.registry,
213-
registryNames,
214-
})
215-
: [];
216-
const searched = query ? await applySearch(tagged, query, registryNames) : null;
217+
const searchContext = query ? { status: localModelStatus() } : null;
218+
const routineUpdate =
219+
searchContext?.status.status === "unavailable" ||
220+
(searchContext?.status.status === "ready" &&
221+
artifactRevision !== undefined &&
222+
cachedLocalVectorRevision() !== artifactRevision);
223+
const shouldPrepare = args["on-device"] === true || routineUpdate;
224+
let warnings: string[] = [];
225+
let effectiveStatus = searchContext?.status;
226+
if (searchContext && shouldPrepare) {
227+
warnings = await prepareOnDeviceTier({
228+
assumedYes: args.yes === true,
229+
artifactRevision,
230+
canPrompt: process.stdout.isTTY === true && !json,
231+
registry: config.registry,
232+
registryNames,
233+
status: searchContext.status,
234+
});
235+
// A successful preparation can move not-asked/unavailable to ready. Read
236+
// the state owner again rather than carrying the pre-download snapshot.
237+
effectiveStatus = localModelStatus();
238+
}
239+
const searched = effectiveStatus
240+
? await applySearch(tagged, query, registryNames, effectiveStatus)
241+
: null;
217242
if (searched) warnings.push(...searched.warnings);
218243
const matching = searched ? searched.items : tagged;
219244

@@ -250,7 +275,7 @@ export default defineCommand({
250275
].filter(Boolean);
251276
console.log(`No items match ${criteria.join(" and ")}.`);
252277
}
253-
if (query) await offerLocalModel(0, json, config.registry);
278+
if (query) await offerLocalModel(0, json, config.registry, artifactRevision);
254279
return;
255280
}
256281

@@ -322,7 +347,7 @@ export default defineCommand({
322347
// reads as the tool arguing with itself.
323348
if (warnings.length === 0) {
324349
reportLocalModelOption(json);
325-
await offerLocalModel(matching.length, json, config.registry);
350+
await offerLocalModel(matching.length, json, config.registry, artifactRevision);
326351
}
327352
}
328353
}
@@ -465,11 +490,16 @@ interface SearchOutcome<T> {
465490

466491
async function applySearch<
467492
T extends { name: string; title: string; description: string; tags?: string[] },
468-
>(items: T[], query: string, registryNames: ReadonlySet<string>): Promise<SearchOutcome<T>> {
493+
>(
494+
items: T[],
495+
query: string,
496+
registryNames: ReadonlySet<string>,
497+
status: LocalModelStatus,
498+
): Promise<SearchOutcome<T>> {
469499
const warnings: string[] = [];
470500
// On-device meaning search, when the user opted into the model. Free and
471501
// offline, and it answers phrasings word matching cannot reach.
472-
if (localModelStatus().status === "ready") {
502+
if (status.status === "ready") {
473503
try {
474504
const ranking = await localSemanticRanking(query);
475505
if (ranking) {
@@ -554,6 +584,7 @@ async function offerLocalModel(
554584
matchCount: number,
555585
json: boolean,
556586
registryBaseUrl: string,
587+
artifactRevision?: string,
557588
): Promise<void> {
558589
if (json || !process.stdout.isTTY) return;
559590
if (localModelStatus().status !== "not-asked") return;
@@ -573,7 +604,9 @@ async function offerLocalModel(
573604
// The vectors come from the registry rather than the package, so consent is
574605
// also the moment to fetch them. A failure here is reported: the alternative
575606
// is an offline tier the user turned on that silently never ranks anything.
576-
const vectors = hasLocalVectors() || (await fetchLocalVectors(registryBaseUrl));
607+
const vectors =
608+
hasLocalVectors() ||
609+
(await fetchLocalVectors(registryBaseUrl, { expectedRevision: artifactRevision }));
577610
console.log(
578611
c.dim(
579612
vectors

‎packages/cli/src/registry/localModel.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ const MODELS_DIR = join(homedir(), ".hyperframes", "models");
4444
* catalog vectors were produced by a specific set of weights.
4545
*/
4646
const MODEL_REPO = "Xenova/bge-small-en-v1.5";
47-
const MODEL_REVISION = "ea104dacec62c0de699686887e3f920caeb4f3e3";
47+
export const LOCAL_MODEL_REVISION = "ea104dacec62c0de699686887e3f920caeb4f3e3";
4848

4949
/**
5050
* The quantized export, 32 MB, not the 126 MB full-precision one.
@@ -63,13 +63,13 @@ interface ModelFile {
6363

6464
export const LOCAL_MODEL_ARTIFACTS: ReadonlyArray<ModelFile> = [
6565
{
66-
url: `https://huggingface.co/${MODEL_REPO}/resolve/${MODEL_REVISION}/onnx/model_quantized.onnx`,
66+
url: `https://huggingface.co/${MODEL_REPO}/resolve/${LOCAL_MODEL_REVISION}/onnx/model_quantized.onnx`,
6767
dest: () => localModelPath(),
6868
bytes: 34_014_426,
6969
sha256: "6c9c6101a956d62dfb5e7190c538226c0c5bb9cb27b651234b6df063ee7dbfe4",
7070
},
7171
{
72-
url: `https://huggingface.co/${MODEL_REPO}/resolve/${MODEL_REVISION}/tokenizer.json`,
72+
url: `https://huggingface.co/${MODEL_REPO}/resolve/${LOCAL_MODEL_REVISION}/tokenizer.json`,
7373
dest: () => localTokenizerPath(),
7474
bytes: 711_396,
7575
sha256: "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66",

0 commit comments

Comments
 (0)