@crossworks/client-types 0.300.52 → 0.300.53

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.300.52",
3
+ "version": "0.300.53",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -0,0 +1,96 @@
1
+ /**
2
+ * What a write re-indexes (arch plan A10 #7), from the kind registry's
3
+ * `indexed` field, against the matrix recorded on main
4
+ * (server/web/server/a10-content-changed.main.json) with the changes named
5
+ * cell by cell (a10-content-changed.changes.json).
6
+ *
7
+ * The db test there runs each write path through its real service; this
8
+ * pins the registry to the same cells, so a field's work cannot change
9
+ * without a named cell. Creates, moves and deletes are not field changes
10
+ * (the INSERT trigger announces a create; a move or a delete re-indexes
11
+ * nothing), and the `-same` cells test the services' value compare, not the
12
+ * registry: those are the db test's alone.
13
+ */
14
+ import { readFileSync } from 'node:fs';
15
+ import { join } from 'node:path';
16
+ import { describe, expect, it } from 'vitest';
17
+ import { ITEM_KINDS, ITEM_KIND_NAMES, indexWorkFor, kindSpecOf } from './kinds';
18
+
19
+ const DIR = join(__dirname, '../../../server/web/server');
20
+ const main = JSON.parse(readFileSync(join(DIR, 'a10-content-changed.main.json'), 'utf8')) as Record<
21
+ string,
22
+ string
23
+ >;
24
+ const changes = JSON.parse(readFileSync(join(DIR, 'a10-content-changed.changes.json'), 'utf8')) as {
25
+ cells: Record<string, { now: string }>;
26
+ };
27
+
28
+ /** The registry field a cell's write path changes, by path. */
29
+ const FIELD_OF_PATH: Record<string, Record<string, string>> = {
30
+ '*': { rename: 'title', tags: 'tags' },
31
+ draw: { commit: 'scene' },
32
+ page: { commit: 'doc', 'edit:doc-reindex-false': 'doc' },
33
+ secret: { 'edit:note': 'sealed' },
34
+ contact: { 'edit:cell': 'cell' },
35
+ file: { indexing: 'indexing' },
36
+ };
37
+
38
+ function fieldOf(kind: string, path: string): string | null {
39
+ const own = FIELD_OF_PATH[kind]?.[path] ?? FIELD_OF_PATH['*']?.[path];
40
+ if (own) return own;
41
+ const m = /^edit:([a-z_]+)$/.exec(path);
42
+ return m ? m[1]! : null;
43
+ }
44
+
45
+ describe('the kind registry says what a write re-indexes (A10 #7)', () => {
46
+ const now: Record<string, string> = { ...main };
47
+ for (const [k, v] of Object.entries(changes.cells)) now[k] = v.now;
48
+ const cells = Object.entries(now).filter(([key]) => {
49
+ const [kind, path] = key.split('|') as [string, string];
50
+ return !path.endsWith('-same') && fieldOf(kind, path) !== null;
51
+ });
52
+
53
+ it('covers the field cells of the recorded matrix', () => {
54
+ expect(cells.length).toBeGreaterThan(30);
55
+ });
56
+
57
+ it.each(cells)('%s', (key, want) => {
58
+ const [kind, path] = key.split('|') as [string, string];
59
+ const field = fieldOf(kind, path)!;
60
+ expect(Object.keys(kindSpecOf(kind)!.indexed), `${kind} names ${field}`).toContain(field);
61
+ expect(indexWorkFor(kind, [field]) ?? 'none').toBe(want);
62
+ });
63
+
64
+ it('a write takes the most work any changed field asks for, once', () => {
65
+ expect(indexWorkFor('note', ['title', 'content'])).toBe('extract');
66
+ expect(indexWorkFor('note', ['title', 'tags'])).toBe('embed');
67
+ expect(indexWorkFor('note', ['tags'])).toBeNull();
68
+ expect(indexWorkFor('note', [])).toBeNull();
69
+ expect(indexWorkFor('table', ['cells'])).toBe('embed');
70
+ expect(indexWorkFor('table', ['cells', 'schema'])).toBe('extract');
71
+ });
72
+
73
+ it('a field or a kind the registry does not name asks for nothing', () => {
74
+ expect(indexWorkFor('note', ['nonsense'])).toBeNull();
75
+ expect(indexWorkFor('not_a_kind', ['title'])).toBeNull();
76
+ expect(indexWorkFor('note', ['toString'])).toBeNull();
77
+ });
78
+
79
+ it('only a kind the extractor reads, or an app, re-indexes on a write', () => {
80
+ // An app is not extracted by default (a worker's target_types may add
81
+ // it), and its publish re-indexes as it did on main.
82
+ for (const t of ITEM_KIND_NAMES) {
83
+ const works = Object.values(ITEM_KINDS[t].indexed as Record<string, unknown>).filter(Boolean);
84
+ if (works.length && !ITEM_KINDS[t].extract) expect(t).toBe('app');
85
+ }
86
+ });
87
+
88
+ it('never asks a model pass of a title alone where main did not', () => {
89
+ // The kinds whose rename already re-extracted on main (the title is in
90
+ // the body the summary reads); every other title only re-embeds.
91
+ const extractTitle = ITEM_KIND_NAMES.filter(
92
+ (t) => (ITEM_KINDS[t].indexed as Record<string, unknown>).title === 'extract',
93
+ );
94
+ expect(extractTitle).toEqual(['secret', 'task', 'event']);
95
+ });
96
+ });
package/src/kinds.ts CHANGED
@@ -17,7 +17,10 @@
17
17
  * - the lists of ./kind-lists (A10 #12): extract, corpusMap, contextRef,
18
18
  * embeds, mentionTarget, linkServes, exportAs, accepted, searchTool,
19
19
  * peerPick, documentTitle. A literal list of kind names anywhere else is
20
- * an arch count pinned at 0 (eslint-rules/arch-counts.mjs handKindLists).
20
+ * an arch count pinned at 0 (eslint-rules/arch-counts.mjs handKindLists);
21
+ * - what a write re-indexes (A10 #7): `indexed`, read by markContentChanged
22
+ * (@mantle/db) and indexWorkFor below; a hand re-index anywhere else is
23
+ * an arch count pinned at 0 (eslint-rules/no-hand-reindex.mjs).
21
24
  *
22
25
  * Each field holds the value the code had when the registry came in (A1).
23
26
  * Who may share or see a kind changes here only as a reviewed diff of the
@@ -119,8 +122,29 @@ export type KindSpec = {
119
122
  readonly peerPick: boolean;
120
123
  /** Its title names a document, not a thing the user does (entity-names). */
121
124
  readonly documentTitle: boolean;
125
+
126
+ // ── A10 #7: what a write re-indexes.
127
+
128
+ /** Every field a write of this kind may change, with the index work its
129
+ * change redoes (markContentChanged, @mantle/db): 'embed', 'extract', or
130
+ * false (the field feeds no index). A write names the fields it changed;
131
+ * the most work any of them asks for is done once. Each value holds what
132
+ * main did at v0.300.48, where a10-content-changed.main.json was
133
+ * recorded, except the cells
134
+ * a10-content-changed.changes.json names. Turning a field to 'extract'
135
+ * makes every save of it a model call: a cost decision, never a tidy-up. */
136
+ readonly indexed: Readonly<Record<string, IndexWork | false>>;
122
137
  };
123
138
 
139
+ /** What a change of an indexed field makes the extractor redo (A10 #7).
140
+ * 'embed': the vector only, rebuilt from the title and the summary the item
141
+ * keeps, or with none from the title and the text read locally (one
142
+ * embedding on the local embedder, never a model call; a table also
143
+ * rebuilds its profile passages, locally). 'extract': the whole pass (the
144
+ * summary, the vector, facts and entities: one model call). There is no
145
+ * summary-only pass: the summary and the facts come from one call. */
146
+ export type IndexWork = 'embed' | 'extract';
147
+
124
148
  /** The formats a kind downloads as by default. */
125
149
  export type KindExportFormat = 'docx' | 'xlsx' | 'svg';
126
150
 
@@ -148,6 +172,7 @@ export const ITEM_KINDS = {
148
172
  searchTool: true,
149
173
  peerPick: false,
150
174
  documentTitle: false,
175
+ indexed: {},
151
176
  },
152
177
  email: {
153
178
  class: 'admin_only',
@@ -170,6 +195,7 @@ export const ITEM_KINDS = {
170
195
  searchTool: true,
171
196
  peerPick: true,
172
197
  documentTitle: false,
198
+ indexed: {},
173
199
  },
174
200
  email_thread: {
175
201
  class: 'admin_only',
@@ -192,6 +218,7 @@ export const ITEM_KINDS = {
192
218
  searchTool: true,
193
219
  peerPick: true,
194
220
  documentTitle: false,
221
+ indexed: {},
195
222
  },
196
223
  file: {
197
224
  class: 'workspace',
@@ -221,6 +248,7 @@ export const ITEM_KINDS = {
221
248
  searchTool: true,
222
249
  peerPick: true,
223
250
  documentTitle: true,
251
+ indexed: { title: 'embed', content: 'extract', indexing: 'extract', tags: false },
224
252
  },
225
253
  note: {
226
254
  class: 'workspace',
@@ -250,6 +278,7 @@ export const ITEM_KINDS = {
250
278
  searchTool: true,
251
279
  peerPick: true,
252
280
  documentTitle: false,
281
+ indexed: { title: 'embed', content: 'extract', tags: false },
253
282
  },
254
283
  sermon: {
255
284
  class: 'admin_only',
@@ -272,6 +301,7 @@ export const ITEM_KINDS = {
272
301
  searchTool: true,
273
302
  peerPick: true,
274
303
  documentTitle: true,
304
+ indexed: {},
275
305
  },
276
306
  contact: {
277
307
  class: 'admin_only',
@@ -301,6 +331,16 @@ export const ITEM_KINDS = {
301
331
  searchTool: true,
302
332
  peerPick: true,
303
333
  documentTitle: false,
334
+ indexed: {
335
+ first_name: 'extract',
336
+ last_name: 'extract',
337
+ company: 'extract',
338
+ emails: 'extract',
339
+ description: 'extract',
340
+ country_code: false,
341
+ cell: false,
342
+ tags: false,
343
+ },
304
344
  },
305
345
  secret: {
306
346
  class: 'admin_only',
@@ -330,6 +370,13 @@ export const ITEM_KINDS = {
330
370
  searchTool: true,
331
371
  peerPick: false,
332
372
  documentTitle: false,
373
+ indexed: {
374
+ title: 'extract',
375
+ description: 'extract',
376
+ kind: 'extract',
377
+ tags: 'extract',
378
+ sealed: false,
379
+ },
333
380
  },
334
381
  task: {
335
382
  class: 'workspace',
@@ -359,6 +406,18 @@ export const ITEM_KINDS = {
359
406
  searchTool: true,
360
407
  peerPick: true,
361
408
  documentTitle: false,
409
+ indexed: {
410
+ title: 'extract',
411
+ body: 'extract',
412
+ status: 'extract',
413
+ priority: 'extract',
414
+ due_at: 'extract',
415
+ todos: 'extract',
416
+ reviewed: 'extract',
417
+ archived_at: false,
418
+ rank: false,
419
+ tags: false,
420
+ },
362
421
  },
363
422
  event: {
364
423
  class: 'workspace',
@@ -388,6 +447,17 @@ export const ITEM_KINDS = {
388
447
  searchTool: true,
389
448
  peerPick: true,
390
449
  documentTitle: false,
450
+ indexed: {
451
+ title: 'extract',
452
+ body: 'extract',
453
+ starts_at: 'extract',
454
+ ends_at: 'extract',
455
+ location: 'extract',
456
+ recur: false,
457
+ remind: false,
458
+ timezone: false,
459
+ tags: false,
460
+ },
391
461
  },
392
462
  printer_project: {
393
463
  class: 'admin_only',
@@ -410,6 +480,7 @@ export const ITEM_KINDS = {
410
480
  searchTool: true,
411
481
  peerPick: true,
412
482
  documentTitle: false,
483
+ indexed: {},
413
484
  },
414
485
  telegram_message: {
415
486
  class: 'conversation',
@@ -432,6 +503,7 @@ export const ITEM_KINDS = {
432
503
  searchTool: true,
433
504
  peerPick: true,
434
505
  documentTitle: false,
506
+ indexed: {},
435
507
  },
436
508
  page: {
437
509
  class: 'workspace',
@@ -461,6 +533,7 @@ export const ITEM_KINDS = {
461
533
  searchTool: true,
462
534
  peerPick: true,
463
535
  documentTitle: false,
536
+ indexed: { title: 'embed', doc: 'extract', look: false, tags: false },
464
537
  },
465
538
  table: {
466
539
  class: 'workspace',
@@ -490,6 +563,7 @@ export const ITEM_KINDS = {
490
563
  searchTool: false,
491
564
  peerPick: true,
492
565
  documentTitle: false,
566
+ indexed: { title: 'embed', cells: 'embed', schema: 'extract', look: false, tags: false },
493
567
  },
494
568
  mantle_peer: {
495
569
  class: 'admin_only',
@@ -512,6 +586,7 @@ export const ITEM_KINDS = {
512
586
  searchTool: false,
513
587
  peerPick: false,
514
588
  documentTitle: false,
589
+ indexed: {},
515
590
  },
516
591
  documentation: {
517
592
  class: 'admin_only',
@@ -534,6 +609,7 @@ export const ITEM_KINDS = {
534
609
  searchTool: true,
535
610
  peerPick: true,
536
611
  documentTitle: true,
612
+ indexed: { content: 'extract' },
537
613
  },
538
614
  journal: {
539
615
  class: 'admin_only',
@@ -556,6 +632,7 @@ export const ITEM_KINDS = {
556
632
  searchTool: true,
557
633
  peerPick: true,
558
634
  documentTitle: false,
635
+ indexed: { title: 'embed', body: 'extract', kind: false, entry_date: false, tags: false },
559
636
  },
560
637
  location: {
561
638
  class: 'admin_only',
@@ -578,6 +655,14 @@ export const ITEM_KINDS = {
578
655
  searchTool: false,
579
656
  peerPick: true,
580
657
  documentTitle: false,
658
+ indexed: {
659
+ title: 'embed',
660
+ body: 'extract',
661
+ address: 'extract',
662
+ coordinates: false,
663
+ source: false,
664
+ tags: false,
665
+ },
581
666
  },
582
667
  app: {
583
668
  class: 'workspace',
@@ -607,6 +692,7 @@ export const ITEM_KINDS = {
607
692
  searchTool: false,
608
693
  peerPick: true,
609
694
  documentTitle: false,
695
+ indexed: { source: 'extract' },
610
696
  },
611
697
  formula: {
612
698
  class: 'workspace',
@@ -636,6 +722,7 @@ export const ITEM_KINDS = {
636
722
  searchTool: true,
637
723
  peerPick: true,
638
724
  documentTitle: false,
725
+ indexed: { title: 'embed', spec: 'extract', tags: false },
639
726
  },
640
727
  draw: {
641
728
  class: 'workspace',
@@ -665,6 +752,7 @@ export const ITEM_KINDS = {
665
752
  searchTool: true,
666
753
  peerPick: true,
667
754
  documentTitle: false,
755
+ indexed: { title: 'embed', scene: 'extract', look: false, tags: false },
668
756
  },
669
757
  recall: {
670
758
  class: 'workspace',
@@ -697,6 +785,7 @@ export const ITEM_KINDS = {
697
785
  searchTool: false,
698
786
  peerPick: true,
699
787
  documentTitle: false,
788
+ indexed: {},
700
789
  },
701
790
  } as const satisfies Record<string, KindSpec>;
702
791
 
@@ -769,3 +858,22 @@ export function treeKindsBy(key: 'order' | 'liveOrder'): readonly RegistryTreeKi
769
858
  .sort((a, b) => a[key] - b[key])
770
859
  .map((t) => t.kind as RegistryTreeKind);
771
860
  }
861
+
862
+ // ── A10 #7: what a write re-indexes ─────────────────────────────────────────
863
+
864
+ /** The fields a write of kind `K` may name (its `indexed` keys). */
865
+ export type IndexedField<K extends ItemKind> = keyof Kinds[K]['indexed'] & string;
866
+
867
+ /** The most work any of `fields` asks of an item of `type` (the registry's
868
+ * `indexed`), or null when none feeds its index. A field the kind does not
869
+ * name asks for nothing. */
870
+ export function indexWorkFor(type: string, fields: readonly string[]): IndexWork | null {
871
+ const indexed: Readonly<Record<string, IndexWork | false>> = kindSpecOf(type)?.indexed ?? {};
872
+ let work: IndexWork | null = null;
873
+ for (const f of fields) {
874
+ const w = Object.prototype.hasOwnProperty.call(indexed, f) ? indexed[f] : false;
875
+ if (w === 'extract') return 'extract';
876
+ if (w === 'embed') work = 'embed';
877
+ }
878
+ return work;
879
+ }