@bendyline/gezk 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -40,6 +40,60 @@ declare const RepoRelativePathSchema: z.ZodString;
40
40
  declare const DEFAULT_EMBEDDING_ONNX_FILE = "onnx/model.onnx";
41
41
  /** The tokenizer definition a profile pins when `tokenizer.file` is absent. */
42
42
  declare const DEFAULT_EMBEDDING_TOKENIZER_FILE = "tokenizer.json";
43
+ /**
44
+ * One more file the runtime loads beside the graph and the tokenizer (0.8).
45
+ * Large graphs keep their weights in an external-data sidecar
46
+ * (`onnx/model.onnx_data`), so a digest of the graph file alone pins a
47
+ * header and none of the weights; configs that steer loading belong here too.
48
+ */
49
+ declare const EmbeddingModelFileSchema: z.ZodObject<{
50
+ path: z.ZodString;
51
+ digest: z.ZodOptional<z.ZodString>;
52
+ }, z.core.$strip>;
53
+ type EmbeddingModelFile = z.infer<typeof EmbeddingModelFileSchema>;
54
+ /**
55
+ * How a multimodal profile turned media into vectors (0.8). Query vectors
56
+ * depend only on the text side, so none of this enters `sameVectorSpace`;
57
+ * it is the provenance a builder needs to reproduce a catalog's media rows,
58
+ * and the settings media floors are calibrated against.
59
+ */
60
+ declare const EmbeddingMediaSchema: z.ZodObject<{
61
+ image: z.ZodOptional<z.ZodObject<{
62
+ encoder: z.ZodObject<{
63
+ onnxFile: z.ZodString;
64
+ onnxDigest: z.ZodOptional<z.ZodString>;
65
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
66
+ path: z.ZodString;
67
+ digest: z.ZodOptional<z.ZodString>;
68
+ }, z.core.$strip>>>;
69
+ }, z.core.$strip>;
70
+ tokenBudget: z.ZodNumber;
71
+ resample: z.ZodEnum<{
72
+ bilinear: "bilinear";
73
+ bicubic: "bicubic";
74
+ }>;
75
+ alpha: z.ZodLiteral<"composite-white">;
76
+ }, z.core.$strip>>;
77
+ video: z.ZodOptional<z.ZodObject<{
78
+ framesPerSecond: z.ZodNumber;
79
+ maxFrames: z.ZodNumber;
80
+ tokenBudgetPerFrame: z.ZodNumber;
81
+ }, z.core.$strip>>;
82
+ audio: z.ZodOptional<z.ZodObject<{
83
+ encoder: z.ZodObject<{
84
+ onnxFile: z.ZodString;
85
+ onnxDigest: z.ZodOptional<z.ZodString>;
86
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
87
+ path: z.ZodString;
88
+ digest: z.ZodOptional<z.ZodString>;
89
+ }, z.core.$strip>>>;
90
+ }, z.core.$strip>;
91
+ sampleRate: z.ZodNumber;
92
+ channels: z.ZodLiteral<1>;
93
+ maxWindowMs: z.ZodNumber;
94
+ }, z.core.$strip>>;
95
+ }, z.core.$strip>;
96
+ type EmbeddingMedia = z.infer<typeof EmbeddingMediaSchema>;
43
97
  /**
44
98
  * The FULL vector-space identity of a catalog's embeddings, self-describing
45
99
  * so any reader can reproduce query vectors: the model by Hugging Face
@@ -55,6 +109,10 @@ declare const KnowledgeEmbeddingProfileObject: z.ZodObject<{
55
109
  revision: z.ZodString;
56
110
  onnxFile: z.ZodOptional<z.ZodString>;
57
111
  onnxDigest: z.ZodOptional<z.ZodString>;
112
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
113
+ path: z.ZodString;
114
+ digest: z.ZodOptional<z.ZodString>;
115
+ }, z.core.$strip>>>;
58
116
  }, z.core.$strip>;
59
117
  tokenizer: z.ZodObject<{
60
118
  kind: z.ZodString;
@@ -68,6 +126,10 @@ declare const KnowledgeEmbeddingProfileObject: z.ZodObject<{
68
126
  }>;
69
127
  normalized: z.ZodBoolean;
70
128
  dimensions: z.ZodNumber;
129
+ truncation: z.ZodOptional<z.ZodObject<{
130
+ method: z.ZodLiteral<"prefix">;
131
+ sourceDimensions: z.ZodNumber;
132
+ }, z.core.$strip>>;
71
133
  maxTokens: z.ZodNumber;
72
134
  queryInstruction: z.ZodString;
73
135
  passageInstruction: z.ZodString;
@@ -93,6 +155,42 @@ declare const KnowledgeEmbeddingProfileObject: z.ZodObject<{
93
155
  center: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
94
156
  }, z.core.$strip>;
95
157
  }, z.core.$strip>;
158
+ media: z.ZodOptional<z.ZodObject<{
159
+ image: z.ZodOptional<z.ZodObject<{
160
+ encoder: z.ZodObject<{
161
+ onnxFile: z.ZodString;
162
+ onnxDigest: z.ZodOptional<z.ZodString>;
163
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
164
+ path: z.ZodString;
165
+ digest: z.ZodOptional<z.ZodString>;
166
+ }, z.core.$strip>>>;
167
+ }, z.core.$strip>;
168
+ tokenBudget: z.ZodNumber;
169
+ resample: z.ZodEnum<{
170
+ bilinear: "bilinear";
171
+ bicubic: "bicubic";
172
+ }>;
173
+ alpha: z.ZodLiteral<"composite-white">;
174
+ }, z.core.$strip>>;
175
+ video: z.ZodOptional<z.ZodObject<{
176
+ framesPerSecond: z.ZodNumber;
177
+ maxFrames: z.ZodNumber;
178
+ tokenBudgetPerFrame: z.ZodNumber;
179
+ }, z.core.$strip>>;
180
+ audio: z.ZodOptional<z.ZodObject<{
181
+ encoder: z.ZodObject<{
182
+ onnxFile: z.ZodString;
183
+ onnxDigest: z.ZodOptional<z.ZodString>;
184
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
185
+ path: z.ZodString;
186
+ digest: z.ZodOptional<z.ZodString>;
187
+ }, z.core.$strip>>>;
188
+ }, z.core.$strip>;
189
+ sampleRate: z.ZodNumber;
190
+ channels: z.ZodLiteral<1>;
191
+ maxWindowMs: z.ZodNumber;
192
+ }, z.core.$strip>>;
193
+ }, z.core.$strip>>;
96
194
  }, z.core.$strip>;
97
195
  type KnowledgeEmbeddingProfile = z.infer<typeof KnowledgeEmbeddingProfileObject>;
98
196
  /**
@@ -104,7 +202,21 @@ type KnowledgeEmbeddingProfile = z.infer<typeof KnowledgeEmbeddingProfileObject>
104
202
  declare function embeddingProfileCenterProblem(profile: KnowledgeEmbeddingProfile): string | null;
105
203
  /** The profile's binary center as a Float32Array, or null for a plain `sign` profile. */
106
204
  declare function embeddingProfileCenter(profile: KnowledgeEmbeddingProfile): Float32Array | null;
107
- /** The profile schema proper: the object shape plus the center rule above. */
205
+ /**
206
+ * Truncation keeps a strict prefix of a unit vector and re-normalizes, so it
207
+ * needs a source wider than the stored width and a normalized profile.
208
+ */
209
+ declare function embeddingProfileTruncationProblem(profile: KnowledgeEmbeddingProfile): string | null;
210
+ /** The width the model itself emits: `truncation.sourceDimensions`, else `dimensions`. */
211
+ declare function embeddingProfileSourceDimensions(profile: KnowledgeEmbeddingProfile): number;
212
+ /**
213
+ * The oldest format version that can describe this profile. Truncation,
214
+ * pinned extra files and a media block are 0.8 vocabulary: an older reader's
215
+ * strip-mode schema would drop them without a word and then embed queries the
216
+ * wrong way, so a catalog using any of them must refuse to open there instead.
217
+ */
218
+ declare function embeddingProfileMinimumFormat(profile: KnowledgeEmbeddingProfile): '0.5' | '0.8';
219
+ /** The profile schema proper: the object shape plus the cross-field rules above. */
108
220
  declare const KnowledgeEmbeddingProfileSchema: z.ZodObject<{
109
221
  id: z.ZodString;
110
222
  model: z.ZodObject<{
@@ -112,6 +224,10 @@ declare const KnowledgeEmbeddingProfileSchema: z.ZodObject<{
112
224
  revision: z.ZodString;
113
225
  onnxFile: z.ZodOptional<z.ZodString>;
114
226
  onnxDigest: z.ZodOptional<z.ZodString>;
227
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
228
+ path: z.ZodString;
229
+ digest: z.ZodOptional<z.ZodString>;
230
+ }, z.core.$strip>>>;
115
231
  }, z.core.$strip>;
116
232
  tokenizer: z.ZodObject<{
117
233
  kind: z.ZodString;
@@ -125,6 +241,10 @@ declare const KnowledgeEmbeddingProfileSchema: z.ZodObject<{
125
241
  }>;
126
242
  normalized: z.ZodBoolean;
127
243
  dimensions: z.ZodNumber;
244
+ truncation: z.ZodOptional<z.ZodObject<{
245
+ method: z.ZodLiteral<"prefix">;
246
+ sourceDimensions: z.ZodNumber;
247
+ }, z.core.$strip>>;
128
248
  maxTokens: z.ZodNumber;
129
249
  queryInstruction: z.ZodString;
130
250
  passageInstruction: z.ZodString;
@@ -150,6 +270,42 @@ declare const KnowledgeEmbeddingProfileSchema: z.ZodObject<{
150
270
  center: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
151
271
  }, z.core.$strip>;
152
272
  }, z.core.$strip>;
273
+ media: z.ZodOptional<z.ZodObject<{
274
+ image: z.ZodOptional<z.ZodObject<{
275
+ encoder: z.ZodObject<{
276
+ onnxFile: z.ZodString;
277
+ onnxDigest: z.ZodOptional<z.ZodString>;
278
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
279
+ path: z.ZodString;
280
+ digest: z.ZodOptional<z.ZodString>;
281
+ }, z.core.$strip>>>;
282
+ }, z.core.$strip>;
283
+ tokenBudget: z.ZodNumber;
284
+ resample: z.ZodEnum<{
285
+ bilinear: "bilinear";
286
+ bicubic: "bicubic";
287
+ }>;
288
+ alpha: z.ZodLiteral<"composite-white">;
289
+ }, z.core.$strip>>;
290
+ video: z.ZodOptional<z.ZodObject<{
291
+ framesPerSecond: z.ZodNumber;
292
+ maxFrames: z.ZodNumber;
293
+ tokenBudgetPerFrame: z.ZodNumber;
294
+ }, z.core.$strip>>;
295
+ audio: z.ZodOptional<z.ZodObject<{
296
+ encoder: z.ZodObject<{
297
+ onnxFile: z.ZodString;
298
+ onnxDigest: z.ZodOptional<z.ZodString>;
299
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
300
+ path: z.ZodString;
301
+ digest: z.ZodOptional<z.ZodString>;
302
+ }, z.core.$strip>>>;
303
+ }, z.core.$strip>;
304
+ sampleRate: z.ZodNumber;
305
+ channels: z.ZodLiteral<1>;
306
+ maxWindowMs: z.ZodNumber;
307
+ }, z.core.$strip>>;
308
+ }, z.core.$strip>>;
153
309
  }, z.core.$strip>;
154
310
  /** The exact repo files a profile pins, with the format defaults applied. */
155
311
  declare function embeddingProfileArtifacts(profile: KnowledgeEmbeddingProfile): {
@@ -157,16 +313,26 @@ declare function embeddingProfileArtifacts(profile: KnowledgeEmbeddingProfile):
157
313
  onnxDigest: string | null;
158
314
  tokenizerFile: string;
159
315
  tokenizerDigest: string | null;
316
+ /** Further text-model files (sidecars, configs), in the profile's order. */
317
+ files: Array<{
318
+ path: string;
319
+ digest: string | null;
320
+ }>;
160
321
  };
161
322
  /**
162
323
  * Whether two profiles describe one vector space, so vectors from either
163
324
  * may be compared: same model files at the same revision, same tokenizer,
164
325
  * pooling, normalization, dimensions, instruction prefixes, encoding and
165
- * int8 quantization. The profile id and `maxTokens` are not compared — the
166
- * first is a label, the second a compile-time bound. A digest counts only
167
- * when both sides declare one: two pins at one revision that hash
168
- * differently name different artifacts, whatever the path says; an
169
- * undeclared digest is simply not a claim.
326
+ * int8 quantization, and the same truncation from the same source width. The
327
+ * profile id and `maxTokens` are not compared — the first is a label, the
328
+ * second a compile-time bound. A digest counts only when both sides declare
329
+ * one: two pins at one revision that hash differently name different
330
+ * artifacts, whatever the path says; an undeclared digest is simply not a
331
+ * claim. Extra `model.files` follow the same rule, path by path.
332
+ *
333
+ * The `media` block is not compared either: a text query vector is valid
334
+ * against a catalog's media rows however their pixels or samples were
335
+ * encoded.
170
336
  *
171
337
  * The binary (stage-1) parameters are deliberately NOT compared. They
172
338
  * describe how a catalog derived its own pre-filter bits, and a reader
@@ -222,11 +388,12 @@ type KnowledgeSignature = z.infer<typeof KnowledgeSignatureSchema>;
222
388
  declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
223
389
  kind: z.ZodLiteral<"gezk-catalog">;
224
390
  formatVersion: z.ZodEnum<{
225
- 0.7: "0.7";
226
391
  0.5: "0.5";
392
+ 0.8: "0.8";
227
393
  0.6: "0.6";
394
+ 0.7: "0.7";
228
395
  }>;
229
- indexSchemaVersion: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
396
+ indexSchemaVersion: z.ZodLiteral<GezkIndexSchemaVersion>;
230
397
  id: z.ZodString;
231
398
  version: z.ZodString;
232
399
  name: z.ZodString;
@@ -256,6 +423,10 @@ declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
256
423
  revision: z.ZodString;
257
424
  onnxFile: z.ZodOptional<z.ZodString>;
258
425
  onnxDigest: z.ZodOptional<z.ZodString>;
426
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
427
+ path: z.ZodString;
428
+ digest: z.ZodOptional<z.ZodString>;
429
+ }, z.core.$strip>>>;
259
430
  }, z.core.$strip>;
260
431
  tokenizer: z.ZodObject<{
261
432
  kind: z.ZodString;
@@ -269,6 +440,10 @@ declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
269
440
  }>;
270
441
  normalized: z.ZodBoolean;
271
442
  dimensions: z.ZodNumber;
443
+ truncation: z.ZodOptional<z.ZodObject<{
444
+ method: z.ZodLiteral<"prefix">;
445
+ sourceDimensions: z.ZodNumber;
446
+ }, z.core.$strip>>;
272
447
  maxTokens: z.ZodNumber;
273
448
  queryInstruction: z.ZodString;
274
449
  passageInstruction: z.ZodString;
@@ -294,6 +469,42 @@ declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
294
469
  center: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
295
470
  }, z.core.$strip>;
296
471
  }, z.core.$strip>;
472
+ media: z.ZodOptional<z.ZodObject<{
473
+ image: z.ZodOptional<z.ZodObject<{
474
+ encoder: z.ZodObject<{
475
+ onnxFile: z.ZodString;
476
+ onnxDigest: z.ZodOptional<z.ZodString>;
477
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
478
+ path: z.ZodString;
479
+ digest: z.ZodOptional<z.ZodString>;
480
+ }, z.core.$strip>>>;
481
+ }, z.core.$strip>;
482
+ tokenBudget: z.ZodNumber;
483
+ resample: z.ZodEnum<{
484
+ bilinear: "bilinear";
485
+ bicubic: "bicubic";
486
+ }>;
487
+ alpha: z.ZodLiteral<"composite-white">;
488
+ }, z.core.$strip>>;
489
+ video: z.ZodOptional<z.ZodObject<{
490
+ framesPerSecond: z.ZodNumber;
491
+ maxFrames: z.ZodNumber;
492
+ tokenBudgetPerFrame: z.ZodNumber;
493
+ }, z.core.$strip>>;
494
+ audio: z.ZodOptional<z.ZodObject<{
495
+ encoder: z.ZodObject<{
496
+ onnxFile: z.ZodString;
497
+ onnxDigest: z.ZodOptional<z.ZodString>;
498
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
499
+ path: z.ZodString;
500
+ digest: z.ZodOptional<z.ZodString>;
501
+ }, z.core.$strip>>>;
502
+ }, z.core.$strip>;
503
+ sampleRate: z.ZodNumber;
504
+ channels: z.ZodLiteral<1>;
505
+ maxWindowMs: z.ZodNumber;
506
+ }, z.core.$strip>>;
507
+ }, z.core.$strip>>;
297
508
  }, z.core.$strip>;
298
509
  chunking: z.ZodObject<{
299
510
  id: z.ZodString;
@@ -335,6 +546,11 @@ declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
335
546
  chunks: z.ZodNumber;
336
547
  shards: z.ZodNumber;
337
548
  assets: z.ZodOptional<z.ZodNumber>;
549
+ media: z.ZodOptional<z.ZodObject<{
550
+ image: z.ZodNumber;
551
+ video: z.ZodNumber;
552
+ audio: z.ZodNumber;
553
+ }, z.core.$strip>>;
338
554
  }, z.core.$strip>;
339
555
  files: z.ZodArray<z.ZodObject<{
340
556
  path: z.ZodString;
@@ -356,9 +572,10 @@ declare const KnowledgeCatalogManifestSchema: z.ZodObject<{
356
572
  }, z.core.$strict>>;
357
573
  requires: z.ZodObject<{
358
574
  formatVersion: z.ZodEnum<{
359
- 0.7: "0.7";
360
575
  0.5: "0.5";
576
+ 0.8: "0.8";
361
577
  0.6: "0.6";
578
+ 0.7: "0.7";
362
579
  }>;
363
580
  features: z.ZodOptional<z.ZodArray<z.ZodString>>;
364
581
  }, z.core.$strip>;
@@ -480,9 +697,10 @@ type KnowledgeRegistryEntry = z.infer<typeof KnowledgeRegistryEntrySchema>;
480
697
  declare const KnowledgeRegistryIndexSchema: z.ZodObject<{
481
698
  kind: z.ZodLiteral<"gezk-registry">;
482
699
  formatVersion: z.ZodEnum<{
483
- 0.7: "0.7";
484
700
  0.5: "0.5";
701
+ 0.8: "0.8";
485
702
  0.6: "0.6";
703
+ 0.7: "0.7";
486
704
  }>;
487
705
  publisher: z.ZodObject<{
488
706
  id: z.ZodString;
@@ -541,29 +759,39 @@ declare function parseKnowledgeUri(raw: string): KnowledgeUri | null;
541
759
 
542
760
  /** Container-level constants of the `.gezk` format. */
543
761
  /**
544
- * Public format version this implementation writes. `0.x` is preliminary:
545
- * breaking changes may land in any minor until 1.0, and a reader supports
546
- * exactly the versions it names (see {@link GEZK_FORMAT_GENERATIONS}).
762
+ * Newest public format version this implementation writes. `0.x` is
763
+ * preliminary: breaking changes may land in any minor until 1.0, and a reader
764
+ * supports exactly the versions it names (see {@link GEZK_FORMAT_GENERATIONS}).
765
+ * The compiler writes the OLDEST generation that can express a catalog (0.7
766
+ * unless it uses 0.8 vocabulary), so catalog updates keep reaching readers
767
+ * that predate the newest generation.
547
768
  */
548
- declare const GEZK_FORMAT_VERSION = "0.7";
549
- /** SQLite schema generation this implementation writes (`PRAGMA user_version`). */
550
- declare const GEZK_INDEX_SCHEMA_VERSION = 4;
769
+ declare const GEZK_FORMAT_VERSION = "0.8";
770
+ /** SQLite schema generation paired with {@link GEZK_FORMAT_VERSION} (`PRAGMA user_version`). */
771
+ declare const GEZK_INDEX_SCHEMA_VERSION = 5;
551
772
  /**
552
773
  * Every (formatVersion, indexSchemaVersion) pairing this implementation
553
- * reads. The writer always emits the current pair; older generations stay
554
- * readable so a catalog published under an earlier 0.x keeps opening after
555
- * a reader upgrade. A manifest that pairs the two differently is corrupt.
774
+ * reads. The writer emits the oldest pair that can express a catalog; older
775
+ * generations stay readable so a catalog published under an earlier 0.x
776
+ * keeps opening after a reader upgrade. A manifest that pairs the two
777
+ * differently is corrupt.
556
778
  */
557
779
  declare const GEZK_FORMAT_GENERATIONS: {
558
780
  readonly '0.5': 2;
559
781
  readonly '0.6': 3;
560
782
  readonly '0.7': 4;
783
+ readonly '0.8': 5;
561
784
  };
562
785
  type GezkFormatVersion = keyof typeof GEZK_FORMAT_GENERATIONS;
563
786
  type GezkIndexSchemaVersion = (typeof GEZK_FORMAT_GENERATIONS)[GezkFormatVersion];
564
787
  declare const GEZK_SUPPORTED_FORMAT_VERSIONS: [GezkFormatVersion, ...GezkFormatVersion[]];
565
788
  declare const GEZK_SUPPORTED_INDEX_SCHEMA_VERSIONS: [GezkIndexSchemaVersion, ...GezkIndexSchemaVersion[]];
566
789
  declare function isSupportedFormatVersion(value: unknown): value is GezkFormatVersion;
790
+ /**
791
+ * Whether `version` is `minimum` or a later generation. Generations are
792
+ * ordered by their index schema, so this never parses version strings.
793
+ */
794
+ declare function formatAtLeast(version: GezkFormatVersion, minimum: GezkFormatVersion): boolean;
567
795
  declare function isSupportedIndexSchemaVersion(value: unknown): value is GezkIndexSchemaVersion;
568
796
  /** `PRAGMA application_id` for every database in a catalog: 'GEZK'. */
569
797
  declare const GEZK_APPLICATION_ID = 1195727435;
@@ -591,26 +819,24 @@ declare const MAX_KNOWLEDGE_TOPIC_DEPTH = 16;
591
819
  declare const ZIP_FIXED_MTIME: Date;
592
820
 
593
821
  /**
594
- * Index schema 4 DDL. Readers never migrate these. Every table is plain
822
+ * Index schema 4 and 5 DDL. Readers never migrate these. Every table is plain
595
823
  * SQLite (FTS5 is the only virtual-table module used), so any SQLite client
596
- * can read a catalog without extensions.
824
+ * can read a catalog without extensions. The router is identical in both
825
+ * generations; schema 5 adds media columns to the shard `chunks` table.
597
826
  */
598
827
  declare const ROUTER_DDL = "\nCREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL) WITHOUT ROWID;\n\nCREATE TABLE topics(\n id TEXT PRIMARY KEY, parent_id TEXT, name TEXT NOT NULL,\n description TEXT, sort_key TEXT NOT NULL, document_count INTEGER NOT NULL\n);\n\nCREATE TABLE documents(\n id TEXT PRIMARY KEY,\n title TEXT NOT NULL, slug TEXT NOT NULL, summary TEXT,\n language TEXT NOT NULL, topic_id TEXT NOT NULL REFERENCES topics(id),\n ordinal INTEGER,\n shard_id INTEGER NOT NULL,\n chunk_count INTEGER NOT NULL,\n source_url TEXT, source_revision TEXT, source_updated_at TEXT,\n attribution_json TEXT,\n meta_json TEXT,\n body_codec TEXT NOT NULL CHECK (body_codec IN ('none','br')),\n body_blob BLOB NOT NULL\n);\nCREATE INDEX documents_topic ON documents(topic_id, ordinal, slug);\nCREATE INDEX documents_shard ON documents(shard_id);\n\nCREATE TABLE document_locations(\n document_id TEXT NOT NULL REFERENCES documents(id),\n location_id TEXT NOT NULL,\n latitude REAL NOT NULL CHECK (latitude BETWEEN -90 AND 90),\n longitude REAL NOT NULL CHECK (longitude >= -180 AND longitude < 180),\n role TEXT NOT NULL CHECK (role IN ('subject','associated')),\n provenance_json TEXT,\n PRIMARY KEY (document_id, location_id)\n) WITHOUT ROWID;\nCREATE INDEX document_locations_latitude ON document_locations(latitude, longitude, document_id);\nCREATE INDEX document_locations_longitude ON document_locations(longitude, latitude, document_id);\n\n-- Includes the primary placement in documents.topic_id/ordinal as well as\n-- shared TOC references. Bodies, chunks and vectors remain keyed by document id.\nCREATE TABLE topic_documents(\n topic_id TEXT NOT NULL REFERENCES topics(id),\n document_id TEXT NOT NULL REFERENCES documents(id),\n ordinal INTEGER CHECK (ordinal IS NULL OR\n (typeof(ordinal) = 'integer' AND ordinal BETWEEN -2147483648 AND 2147483647)),\n PRIMARY KEY (topic_id, document_id)\n) WITHOUT ROWID;\nCREATE INDEX topic_documents_document ON topic_documents(document_id);\nCREATE INDEX topic_documents_order ON topic_documents(topic_id, ordinal, document_id);\n\nCREATE TABLE aliases(alias TEXT NOT NULL, document_id TEXT NOT NULL,\n PRIMARY KEY (alias, document_id)) WITHOUT ROWID;\n\nCREATE TABLE shards(\n id INTEGER PRIMARY KEY,\n path TEXT NOT NULL,\n chunk_count INTEGER NOT NULL, document_count INTEGER NOT NULL,\n topic_ids_json TEXT NOT NULL, centroid_count INTEGER NOT NULL,\n bytes INTEGER NOT NULL\n);\n\nCREATE TABLE route_centroids(\n id INTEGER PRIMARY KEY,\n shard_id INTEGER NOT NULL REFERENCES shards(id),\n embedding BLOB NOT NULL,\n weight INTEGER NOT NULL\n);\nCREATE INDEX route_centroids_shard ON route_centroids(shard_id);\n\nCREATE VIRTUAL TABLE fts_documents USING fts5(\n title, summary, aliases, document_id UNINDEXED,\n tokenize = 'unicode61 remove_diacritics 2', prefix = '2 3'\n);\n";
599
- /**
600
- * Per-shard tables. Vectors are plain BLOB columns keyed by chunk id:
601
- * `chunk_vectors_bit.v` holds ceil(dim/8) bytes of sign bits (LSB-first; of
602
- * the unit vector for a `sign` profile, of `vector − center` for a
603
- * `centered-sign` profile — the profile echo in the router's meta says
604
- * which) and `chunk_vectors_int8.v` holds dim signed bytes
605
- * (symmetric-linear, scale 127, never centered). Two tables, not one, so a stage-1 scan pages in 48 bytes per row
606
- * rather than the whole record. Rowid alignment invariant:
607
- * chunks.id == chunk_vectors_bit.chunk_id == chunk_vectors_int8.chunk_id ==
608
- * fts_chunks.rowid, dense from 1.
609
- */
610
- declare const SHARD_DDL = "\nCREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL) WITHOUT ROWID;\n\nCREATE TABLE chunks(\n id INTEGER PRIMARY KEY,\n chunk_uid TEXT NOT NULL,\n document_id TEXT NOT NULL,\n ordinal INTEGER NOT NULL,\n title TEXT NOT NULL,\n heading_path TEXT NOT NULL,\n heading_text TEXT NOT NULL,\n line_start INTEGER NOT NULL, line_end INTEGER NOT NULL,\n token_count INTEGER NOT NULL,\n content_hash TEXT NOT NULL,\n text TEXT NOT NULL\n);\nCREATE UNIQUE INDEX chunks_uid ON chunks(chunk_uid);\nCREATE INDEX chunks_document ON chunks(document_id, ordinal);\n\nCREATE VIRTUAL TABLE fts_chunks USING fts5(\n title, heading_text, text,\n content = 'chunks', content_rowid = 'id',\n tokenize = 'unicode61 remove_diacritics 2'\n);\n\nCREATE TABLE chunk_vectors_bit(\n chunk_id INTEGER PRIMARY KEY,\n v BLOB NOT NULL\n);\n\nCREATE TABLE chunk_vectors_int8(\n chunk_id INTEGER PRIMARY KEY,\n v BLOB NOT NULL\n);\n";
828
+ /** Index schema 4 shard DDL (format 0.7): text rows only. */
829
+ declare const SHARD_DDL_V4: string;
830
+ /** Index schema 5 shard DDL (format 0.8): text rows plus media rows. */
831
+ declare const SHARD_DDL_V5: string;
832
+ /** The newest shard DDL. */
833
+ declare const SHARD_DDL: string;
834
+ /** The shard DDL a writer uses for one index schema generation it writes. */
835
+ declare function shardDdlFor(indexSchemaVersion: 4 | 5): string;
611
836
 
612
837
  /**
613
- * Assets: images a catalog ships under `assets/` for its document bodies.
838
+ * Assets: files a catalog ships under `assets/` for its document bodies —
839
+ * images since 0.6, and since 0.8 the audio and video its media rows embed.
614
840
  * A document references one by its archive path (`![alt](assets/x.png)`),
615
841
  * and a reader resolves that against the catalog, never the network. The
616
842
  * rules here are the format's: which files may be assets, how large, and
@@ -627,16 +853,40 @@ declare const KNOWLEDGE_ASSET_TYPES: {
627
853
  readonly webp: "image/webp";
628
854
  readonly svg: "image/svg+xml";
629
855
  };
630
- type KnowledgeAssetExtension = keyof typeof KNOWLEDGE_ASSET_TYPES;
631
- type KnowledgeAssetKind = 'png' | 'jpeg' | 'gif' | 'webp' | 'svg';
856
+ /**
857
+ * Audio and video assets (0.8). A reader hands these bytes to the platform's
858
+ * own media element and never parses them itself; only a catalog builder
859
+ * decodes them, to embed their windows.
860
+ */
861
+ declare const KNOWLEDGE_MEDIA_ASSET_TYPES: {
862
+ readonly mp4: "video/mp4";
863
+ readonly webm: "video/webm";
864
+ readonly mp3: "audio/mpeg";
865
+ readonly m4a: "audio/mp4";
866
+ readonly ogg: "audio/ogg";
867
+ readonly opus: "audio/ogg";
868
+ readonly wav: "audio/wav";
869
+ readonly flac: "audio/flac";
870
+ };
871
+ type KnowledgeImageAssetExtension = keyof typeof KNOWLEDGE_ASSET_TYPES;
872
+ type KnowledgeMediaAssetExtension = keyof typeof KNOWLEDGE_MEDIA_ASSET_TYPES;
873
+ type KnowledgeAssetExtension = KnowledgeImageAssetExtension | KnowledgeMediaAssetExtension;
874
+ /** What the leading bytes can prove; ISO BMFF covers both mp4 and m4a. */
875
+ type KnowledgeAssetKind = 'png' | 'jpeg' | 'gif' | 'webp' | 'svg' | 'isobmff' | 'webm' | 'mp3' | 'ogg' | 'wav' | 'flac';
876
+ type KnowledgeAssetModality = 'image' | 'video' | 'audio';
632
877
  declare const MAX_KNOWLEDGE_ASSET_BYTES: number;
633
878
  declare const MAX_KNOWLEDGE_ASSETS_TOTAL_BYTES: number;
879
+ /** Per-file limit for an audio or video asset (0.8). */
880
+ declare const MAX_KNOWLEDGE_MEDIA_ASSET_BYTES: number;
881
+ /** Combined limit for every audio and video asset in one catalog (0.8). */
882
+ declare const MAX_KNOWLEDGE_MEDIA_ASSETS_TOTAL_BYTES: number;
634
883
  declare const MAX_KNOWLEDGE_ASSET_COUNT = 8192;
635
884
  declare const MAX_KNOWLEDGE_ASSET_PATH_LENGTH = 512;
636
885
  /**
637
886
  * `assets/(<dir>/)*<name>.<ext>` — up to 15 directory segments, each
638
887
  * segment `[A-Za-z0-9._-]` and never starting with a dot (so `.`, `..` and
639
- * hidden files are impossible by construction), extension from the table.
888
+ * hidden files are impossible by construction), extension from the image
889
+ * table (every generation since 0.6) or the media table (0.8).
640
890
  */
641
891
  declare const KNOWLEDGE_ASSET_PATH_PATTERN: RegExp;
642
892
  declare const KnowledgeAssetPathSchema: z.ZodString;
@@ -644,12 +894,28 @@ declare function isKnowledgeAssetPath(path: string): boolean;
644
894
  declare function assetExtension(path: string): KnowledgeAssetExtension | null;
645
895
  /** The media type an asset path implies, from its extension. */
646
896
  declare function assetContentType(path: string): string | null;
647
- /** The kind an extension declares, normalized (`jpg` and `jpeg` are one kind). */
897
+ /** Whether an asset path is audio or video, which only 0.8 catalogs may ship. */
898
+ declare function isKnowledgeMediaAssetPath(path: string): boolean;
899
+ /** What kind of media row an asset can back, from its extension. */
900
+ declare function assetModality(path: string): KnowledgeAssetModality | null;
901
+ /** The per-file size limit for an asset path. */
902
+ declare function maxKnowledgeAssetBytes(path: string): number;
903
+ /**
904
+ * Why a set of asset files breaks the format's size and count limits, or
905
+ * null. Images and media have separate per-file and total budgets; the
906
+ * count limit covers both.
907
+ */
908
+ declare function knowledgeAssetLimitsProblem(files: ReadonlyArray<{
909
+ path: string;
910
+ sizeBytes: number;
911
+ }>): string | null;
912
+ /** The kind an extension declares, normalized (`jpg`/`jpeg`, `mp4`/`m4a`, `ogg`/`opus`). */
648
913
  declare function assetKindForExtension(ext: KnowledgeAssetExtension): KnowledgeAssetKind;
649
914
  /**
650
- * What the leading bytes say the file is. Rasters are recognized by their
651
- * magic numbers; an SVG is UTF-8 text whose first element, after any BOM,
652
- * whitespace, XML declaration, comments and DOCTYPE, is `<svg`.
915
+ * What the leading bytes say the file is. Rasters and audio/video containers
916
+ * are recognized by their magic numbers; an SVG is UTF-8 text whose first
917
+ * element, after any BOM, whitespace, XML declaration, comments and DOCTYPE,
918
+ * is `<svg`.
653
919
  */
654
920
  declare function sniffAssetType(bytes: Uint8Array): KnowledgeAssetKind | null;
655
921
  /**
@@ -686,6 +952,16 @@ declare function topicSortKeyForOrder(order: number): string;
686
952
  * way.
687
953
  */
688
954
 
955
+ /**
956
+ * The unit vector a profile stores or queries with, from the model's raw
957
+ * output: checked against the width the model emits, cut to the stored
958
+ * width when the profile truncates (Matryoshka prefix), then normalized.
959
+ * The compiler (passages and media) and every query embedder call this, so
960
+ * truncation has exactly one definition. The norm is taken over the raw
961
+ * values as given, never over a float32 copy, so a profile without
962
+ * truncation produces bit-for-bit what `l2Normalize` always did.
963
+ */
964
+ declare function profileUnitVector(profile: KnowledgeEmbeddingProfile, raw: ArrayLike<number>): Float32Array;
689
965
  /** int8: symmetric linear, scale 127, −128 never produced. */
690
966
  declare function quantizeInt8(unitVector: ArrayLike<number>): Int8Array;
691
967
  /** `vector − center`, the input to a `centered-sign` profile's bits. */
@@ -701,6 +977,8 @@ declare function quantizeBinary(unitVector: ArrayLike<number>): Uint8Array;
701
977
  /**
702
978
  * Rerank score: dot(float32 unit query, dequantized int8 passage). Passages
703
979
  * were unit vectors, so this approximates cosine; the query is not quantized.
980
+ * Widths must match: a query from an untruncated model scored against a
981
+ * truncated catalog would otherwise rank plausibly over a silent prefix.
704
982
  */
705
983
  declare function rerankScore(query: ArrayLike<number>, passageInt8: Int8Array): number;
706
984
  /** L2-normalize in place-free fashion; throws on a degenerate vector. */
@@ -791,4 +1069,39 @@ declare function spatialManifest(locations: Array<{
791
1069
  location: KnowledgeLocation;
792
1070
  }>): KnowledgeSpatialManifest;
793
1071
 
794
- export { ASSETS_PREFIX, ArtifactDigestSchema, BODY_CODEC_MIN_BYTES, type CatalogDocument, CatalogDocumentSchema, DEFAULT_EMBEDDING_ONNX_FILE, DEFAULT_EMBEDDING_TOKENIZER_FILE, GEZK_APPLICATION_ID, GEZK_EARTH_RADIUS_METERS, GEZK_FORMAT_GENERATIONS, GEZK_FORMAT_VERSION, GEZK_INDEX_SCHEMA_VERSION, GEZK_MANIFEST_KIND, GEZK_MIME_TYPE, GEZK_REGISTRY_KIND, GEZK_SUPPORTED_FORMAT_VERSIONS, GEZK_SUPPORTED_INDEX_SCHEMA_VERSIONS, type GezkFormatVersion, type GezkIndexSchemaVersion, KNOWLEDGE_ASSET_PATH_PATTERN, KNOWLEDGE_ASSET_TYPES, KNOWLEDGE_ID_PATTERN, KNOWLEDGE_MANIFEST_INDEX_SCHEMA_VERSIONS, KNOWLEDGE_VERSION_PATTERN, type KnowledgeAssetExtension, type KnowledgeAssetKind, KnowledgeAssetPathSchema, type KnowledgeBounds, KnowledgeBoundsSchema, type KnowledgeCatalogManifest, KnowledgeCatalogManifestSchema, KnowledgeChunkUidSchema, type KnowledgeChunkingProfile, KnowledgeChunkingProfileSchema, KnowledgeDocumentIdSchema, type KnowledgeDocumentMeta, KnowledgeDocumentMetaSchema, type KnowledgeEmbeddingProfile, KnowledgeEmbeddingProfileSchema, KnowledgeIdSchema, type KnowledgeLocation, KnowledgeLocationSchema, KnowledgeLocationsSchema, KnowledgeManifestFileSchema, KnowledgeOrdinalSchema, type KnowledgeRadius, KnowledgeRadiusSchema, type KnowledgeRegistryEntry, KnowledgeRegistryEntrySchema, type KnowledgeRegistryIndex, KnowledgeRegistryIndexSchema, type KnowledgeSignature, KnowledgeSignatureSchema, type KnowledgeSpatialManifest, KnowledgeSpatialManifestSchema, type KnowledgeTocReference, KnowledgeTocReferenceSchema, type KnowledgeUri, type KnowledgeVectorEncoding, KnowledgeVectorEncodingSchema, KnowledgeVersionSchema, LICENSE_NOTICE_PATH, MANIFEST_PATH, MAX_DOCUMENT_LOCATIONS, MAX_KNOWLEDGE_ASSETS_TOTAL_BYTES, MAX_KNOWLEDGE_ASSET_BYTES, MAX_KNOWLEDGE_ASSET_COUNT, MAX_KNOWLEDGE_ASSET_PATH_LENGTH, MAX_KNOWLEDGE_DOCUMENT_BYTES, MAX_KNOWLEDGE_DOCUMENT_META_BYTES, MAX_KNOWLEDGE_TOPIC_DEPTH, MIMETYPE_PATH, README_PATH, ROUTER_DB_PATH, ROUTER_DDL, RepoRelativePathSchema, SHARD_DDL, SOURCE_NOTICES_PATH, Sha256HexSchema, type SourceNotices, SourceNoticesSchema, ZIP_FIXED_MTIME, assetContentType, assetExtension, assetKindForExtension, canonicalizeJson, centerVector, documentSlug, embeddingProfileArtifacts, embeddingProfileCenter, embeddingProfileCenterProblem, formatKnowledgeUri, isKnowledgeAssetPath, isSupportedFormatVersion, isSupportedIndexSchemaVersion, l2Normalize, locationDistanceMeters, locationInBounds, normalizeLongitude, parseKnowledgeUri, quantizeBinary, quantizeBinaryForProfile, quantizeInt8, radiusBounds, rerankScore, sameVectorSpace, sniffAssetType, spatialManifest, svgInertnessProblem, topicSortKeyForOrder };
1072
+ /**
1073
+ * Words that carry no subject in a search request. Dropping one from an FTS5
1074
+ * OR query is safe: it can only remove hits that matched nothing else, and
1075
+ * anything holding a distinctive term still ranks.
1076
+ *
1077
+ * One list for every keyword-search path — the project index's query builder
1078
+ * and token scorers in the service, the knowledge-catalog reader, and the
1079
+ * phone runtime's memory recall. It lives here, in the format package,
1080
+ * because this is the one package all three can import: the reader must not
1081
+ * depend on core or the service, and core must stay browser-safe.
1082
+ * There were three lists once: a 24-word one behind the project index's FTS5
1083
+ * query, a 14-word one behind area-summary token coverage, and the catalog
1084
+ * reader's function words. Neither project list covered the vocabulary of an
1085
+ * ordinary request, so "Can you create a PowerPoint about France" reached
1086
+ * FTS5 as `"can"* OR "create"* OR "powerpoint"* OR "about"* OR "france"*`.
1087
+ * In the shared library `france` matched nothing at all while
1088
+ * `can`/`about`/`create` matched 66/25/30 rows, so ranking was decided
1089
+ * entirely by the filler: the top document hit was a career memoir, and the
1090
+ * top symbol hit was a heading called "All About DocBlocks" whose only
1091
+ * matched token was `about`. The catalog reader kept `tell`, `please` and
1092
+ * `help` in "Can you tell me how to integrate Azure search with blob
1093
+ * storage?".
1094
+ *
1095
+ * Callers fall back to every token when a query is nothing but these words,
1096
+ * so "how to" and a bare search for "create" still search for what was typed.
1097
+ *
1098
+ * Judgment call worth knowing about: the request verbs `create` and `make`
1099
+ * are stopwords, while `build`, `fix`, `read`, `write`, `update`, `delete`
1100
+ * and `show` are not. The first two are how a user says "produce a thing" and
1101
+ * carry no subject; the rest name real work and real symbols in a codebase.
1102
+ *
1103
+ * Lowercase; compare against a lowercased token.
1104
+ */
1105
+ declare const QUERY_STOP_WORDS: ReadonlySet<string>;
1106
+
1107
+ export { ASSETS_PREFIX, ArtifactDigestSchema, BODY_CODEC_MIN_BYTES, type CatalogDocument, CatalogDocumentSchema, DEFAULT_EMBEDDING_ONNX_FILE, DEFAULT_EMBEDDING_TOKENIZER_FILE, type EmbeddingMedia, EmbeddingMediaSchema, type EmbeddingModelFile, EmbeddingModelFileSchema, GEZK_APPLICATION_ID, GEZK_EARTH_RADIUS_METERS, GEZK_FORMAT_GENERATIONS, GEZK_FORMAT_VERSION, GEZK_INDEX_SCHEMA_VERSION, GEZK_MANIFEST_KIND, GEZK_MIME_TYPE, GEZK_REGISTRY_KIND, GEZK_SUPPORTED_FORMAT_VERSIONS, GEZK_SUPPORTED_INDEX_SCHEMA_VERSIONS, type GezkFormatVersion, type GezkIndexSchemaVersion, KNOWLEDGE_ASSET_PATH_PATTERN, KNOWLEDGE_ASSET_TYPES, KNOWLEDGE_ID_PATTERN, KNOWLEDGE_MANIFEST_INDEX_SCHEMA_VERSIONS, KNOWLEDGE_MEDIA_ASSET_TYPES, KNOWLEDGE_VERSION_PATTERN, type KnowledgeAssetExtension, type KnowledgeAssetKind, type KnowledgeAssetModality, KnowledgeAssetPathSchema, type KnowledgeBounds, KnowledgeBoundsSchema, type KnowledgeCatalogManifest, KnowledgeCatalogManifestSchema, KnowledgeChunkUidSchema, type KnowledgeChunkingProfile, KnowledgeChunkingProfileSchema, KnowledgeDocumentIdSchema, type KnowledgeDocumentMeta, KnowledgeDocumentMetaSchema, type KnowledgeEmbeddingProfile, KnowledgeEmbeddingProfileSchema, KnowledgeIdSchema, type KnowledgeImageAssetExtension, type KnowledgeLocation, KnowledgeLocationSchema, KnowledgeLocationsSchema, KnowledgeManifestFileSchema, type KnowledgeMediaAssetExtension, KnowledgeOrdinalSchema, type KnowledgeRadius, KnowledgeRadiusSchema, type KnowledgeRegistryEntry, KnowledgeRegistryEntrySchema, type KnowledgeRegistryIndex, KnowledgeRegistryIndexSchema, type KnowledgeSignature, KnowledgeSignatureSchema, type KnowledgeSpatialManifest, KnowledgeSpatialManifestSchema, type KnowledgeTocReference, KnowledgeTocReferenceSchema, type KnowledgeUri, type KnowledgeVectorEncoding, KnowledgeVectorEncodingSchema, KnowledgeVersionSchema, LICENSE_NOTICE_PATH, MANIFEST_PATH, MAX_DOCUMENT_LOCATIONS, MAX_KNOWLEDGE_ASSETS_TOTAL_BYTES, MAX_KNOWLEDGE_ASSET_BYTES, MAX_KNOWLEDGE_ASSET_COUNT, MAX_KNOWLEDGE_ASSET_PATH_LENGTH, MAX_KNOWLEDGE_DOCUMENT_BYTES, MAX_KNOWLEDGE_DOCUMENT_META_BYTES, MAX_KNOWLEDGE_MEDIA_ASSETS_TOTAL_BYTES, MAX_KNOWLEDGE_MEDIA_ASSET_BYTES, MAX_KNOWLEDGE_TOPIC_DEPTH, MIMETYPE_PATH, QUERY_STOP_WORDS, README_PATH, ROUTER_DB_PATH, ROUTER_DDL, RepoRelativePathSchema, SHARD_DDL, SHARD_DDL_V4, SHARD_DDL_V5, SOURCE_NOTICES_PATH, Sha256HexSchema, type SourceNotices, SourceNoticesSchema, ZIP_FIXED_MTIME, assetContentType, assetExtension, assetKindForExtension, assetModality, canonicalizeJson, centerVector, documentSlug, embeddingProfileArtifacts, embeddingProfileCenter, embeddingProfileCenterProblem, embeddingProfileMinimumFormat, embeddingProfileSourceDimensions, embeddingProfileTruncationProblem, formatAtLeast, formatKnowledgeUri, isKnowledgeAssetPath, isKnowledgeMediaAssetPath, isSupportedFormatVersion, isSupportedIndexSchemaVersion, knowledgeAssetLimitsProblem, l2Normalize, locationDistanceMeters, locationInBounds, maxKnowledgeAssetBytes, normalizeLongitude, parseKnowledgeUri, profileUnitVector, quantizeBinary, quantizeBinaryForProfile, quantizeInt8, radiusBounds, rerankScore, sameVectorSpace, shardDdlFor, sniffAssetType, spatialManifest, svgInertnessProblem, topicSortKeyForOrder };