@harperfast/template-vue-studio 1.13.6 → 1.14.0

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.
Files changed (36) hide show
  1. package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
  2. package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  3. package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  4. package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
  5. package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  6. package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  7. package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  8. package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
  9. package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  10. package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  11. package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  12. package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  13. package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  14. package/.agents/skills/harper-mcp/AGENTS.md +228 -155
  15. package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  16. package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  17. package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
  18. package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
  19. package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  20. package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  21. package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
  22. package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  23. package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  24. package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  25. package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
  26. package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  27. package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  28. package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  29. package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  30. package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  31. package/agent/skills/harper-mcp/AGENTS.md +228 -155
  32. package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  33. package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  34. package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
  35. package/package.json +1 -1
  36. package/skills-lock.json +7 -7
@@ -5,8 +5,8 @@ metadata:
5
5
  mode: generate
6
6
  sources:
7
7
  - reference/v5/database/schema.md#Vector Indexing
8
- sourceCommit: d4cbc1a7dd400462e4a3243f944b3a75d89b29ca
9
- inputHash: 1dae788bc850ea90
8
+ sourceCommit: 1b103f864df3a0d8444297c00e752c29c2e7e82b
9
+ inputHash: 8f9270223df41d20
10
10
  ---
11
11
 
12
12
  # Vector Indexing
@@ -49,7 +49,7 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
49
49
  });
50
50
  ```
51
51
 
52
- 4. **Apply a function predicate during traversal** using `vectorFilter` (JavaScript API only). The function receives each candidate record and must return a synchronous boolean. It must be side-effect free and fast:
52
+ 4. **Apply a function predicate** using `vectorFilter` (JavaScript API only) for predicates not expressible as conditions. The function receives each candidate record and must return a synchronous boolean. Records are frozen:
53
53
 
54
54
  ```javascript
55
55
  let results = Document.search(
@@ -76,7 +76,7 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
76
76
  });
77
77
  ```
78
78
 
79
- 6. **Include computed distance in results** by adding `$distance` to `select`. Works with both `sort`-based and threshold queries:
79
+ 6. **Include computed distance** in results by adding `$distance` to `select`. Works with both `sort`-based ranking and threshold queries:
80
80
 
81
81
  ```javascript
82
82
  let results = Document.search({
@@ -95,7 +95,10 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
95
95
  });
96
96
  ```
97
97
 
98
- 8. **Tune filtered traversal** with `ef` and `filterExpansion` when a `vectorFilter` is very selective. The visit budget is `ef * filterExpansion` nodes (`filterExpansion` defaults to `24`):
98
+ - `distance` — overrides the index distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
99
+ - `ef` — overrides the search exploration budget. Higher values improve recall at the cost of latency.
100
+
101
+ 8. **Tune filtered traversal** when a `vectorFilter` is very selective. Filtered traversal is bounded by `ef * filterExpansion` nodes visited. Raise either knob to trade latency for recall:
99
102
 
100
103
  ```javascript
101
104
  let results = Document.search(
@@ -108,96 +111,102 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
108
111
  );
109
112
  ```
110
113
 
111
- 9. **Enforce row-level access control** using `rowFilter` on search and subscription targets (JavaScript API only). Attach it in an operation override. For vector queries, `rowFilter` participates in HNSW traversal so callers receive the k nearest _matching_ records:
112
-
113
- ```javascript
114
- function canReadReport(record, context) {
115
- const user = context.user;
116
- if (user?.role?.permission?.super_user) return true;
117
- return user?.username != null && record.ownerId != null && record.ownerId === user.username;
118
- }
114
+ 9. **Configure HNSW index parameters** in the schema directive. Use the parameter table below to choose values:
119
115
 
120
- export class Reports extends tables.Reports {
121
- search(target) {
122
- target.rowFilter = canReadReport;
123
- return super.search(target);
124
- }
116
+ ```graphql
117
+ type Document @table {
118
+ id: Long @primaryKey
119
+ textEmbeddings: [Float]
120
+ @indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
125
121
  }
126
122
  ```
127
123
 
128
- ### HNSW Index Parameters
129
-
130
- Configure parameters directly on `@indexed(type: "HNSW", ...)`:
124
+ | Parameter | Default | Description |
125
+ | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
126
+ | `distance` | `"cosine"` | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"` |
127
+ | `efConstruction` | `100` | Max nodes explored during index construction. Higher = better recall, lower = better performance |
128
+ | `M` | `16` | Preferred connections per graph layer |
129
+ | `optimizeRouting` | `0.5` | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive) |
130
+ | `mL` | computed from `M` | Normalization factor for level generation |
131
+ | `efConstructionSearch` | auto-scaled | Max nodes explored during search. When unset, auto-scales with index size |
132
+ | `quantization` | — | `"int8"` stores vectors quantized to int8 |
133
+ | `filterExpansion` | `24` | Visit-budget multiplier for filtered search: visits at most `ef * filterExpansion` nodes |
131
134
 
132
- | Parameter | Default | Description |
133
- | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
134
- | `distance` | `"cosine"` | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"` |
135
- | `efConstruction` | `100` | Max nodes explored during index construction. Higher = better recall, lower = better performance |
136
- | `M` | `16` | Preferred connections per graph layer |
137
- | `optimizeRouting` | `0.5` | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive) |
138
- | `mL` | computed from `M` | Normalization factor for level generation |
139
- | `efConstructionSearch` | auto-scaled | Max nodes explored during search. When unset, auto-scales with index size |
140
- | `quantization` | — | `"int8"` stores vectors quantized to int8 |
141
- | `filterExpansion` | `24` | Visit-budget multiplier for filtered search: visits at most `ef * filterExpansion` nodes |
135
+ > Use `efConstructionSearch` (not `efSearchConstruction`). Changing `efConstructionSearch` on an existing index does not trigger a rebuild. Changing structural parameters (`distance`, `M`, `efConstruction`, `quantization`) does rebuild the index.
142
136
 
143
- Per-query `sort` descriptor options:
137
+ 10. **Enable vector quantization** with `quantization: "int8"` to reduce index size and memory usage. Graph navigation uses quantized distances; nearest-neighbor `sort` queries are re-ranked against full-precision vectors for exact results:
144
138
 
145
- | Option | Values | Description |
146
- | ---------- | ----------------------------------------- | ------------------------------------------------------ |
147
- | `distance` | `"cosine"`, `"euclidean"`, `"dotProduct"` | Overrides the index's distance function for this query |
148
- | `ef` | integer | Overrides the search exploration budget for this query |
139
+ ```graphql
140
+ type Document @table {
141
+ id: Long @primaryKey
142
+ textEmbeddings: [Float] @indexed(type: "HNSW", quantization: "int8")
143
+ }
144
+ ```
149
145
 
150
146
  ## Examples
151
147
 
152
- **Index with custom HNSW parameters:**
153
-
154
- ```graphql
155
- type Document @table {
156
- id: Long @primaryKey
157
- textEmbeddings: [Float]
158
- @indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
159
- }
160
- ```
161
-
162
- **Index with int8 quantization:**
148
+ ### Basic nearest-neighbor search
163
149
 
164
150
  ```graphql
165
151
  type Document @table {
166
152
  id: Long @primaryKey
167
- textEmbeddings: [Float] @indexed(type: "HNSW", quantization: "int8")
153
+ textEmbeddings: [Float] @indexed(type: "HNSW")
168
154
  }
169
155
  ```
170
156
 
171
- **Nearest-neighbor search with distance included:**
172
-
173
157
  ```javascript
174
158
  let results = Document.search({
175
- select: ['name', '$distance'],
176
159
  sort: { attribute: 'textEmbeddings', target: searchVector },
177
160
  limit: 5,
178
161
  });
179
162
  ```
180
163
 
181
- **Filtered traversal with tuned budget:**
164
+ ### Filtered vector search with row-level access control
182
165
 
183
166
  ```javascript
184
- let results = Document.search(
185
- {
186
- sort: { attribute: 'textEmbeddings', target: searchVector, ef: 200, filterExpansion: 40 },
187
- vectorFilter: (record) => record.category === 'rare',
188
- limit: 10,
189
- },
190
- context,
191
- );
167
+ function canReadReport(record, context) {
168
+ const user = context.user;
169
+ if (user?.role?.permission?.super_user) return true;
170
+ return user?.username != null && record.ownerId != null && record.ownerId === user.username;
171
+ }
172
+
173
+ export class Reports extends tables.Reports {
174
+ get(target) {
175
+ const context = this.getContext();
176
+ if (target.isCollection) {
177
+ target.rowFilter = canReadReport;
178
+ } else if (!canReadReport(this, context)) {
179
+ return new Response(null, { status: 404 });
180
+ }
181
+ return super.get(target);
182
+ }
183
+
184
+ search(target) {
185
+ target.rowFilter = canReadReport;
186
+ return super.search(target);
187
+ }
188
+
189
+ subscribe(request) {
190
+ request.rowFilter = canReadReport;
191
+ return super.subscribe(request);
192
+ }
193
+ }
194
+ ```
195
+
196
+ ### Custom HNSW parameters with cosine distance
197
+
198
+ ```graphql
199
+ type Document @table {
200
+ id: Long @primaryKey
201
+ textEmbeddings: [Float]
202
+ @indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
203
+ }
192
204
  ```
193
205
 
194
206
  ## Notes
195
207
 
196
- - `vectorFilter` and `rowFilter` are available from the JavaScript API only; they cannot be set through REST or QUERY request data.
197
- - `vectorFilter` functions must be synchronous, side-effect free, and fast — they can run once per candidate record visited during traversal; verdicts are memoized per query. Records passed to them are frozen.
198
- - `rowFilter` does not apply to a direct primary-key `get`.
199
- - Changing `efConstructionSearch` on an existing index does not trigger a rebuild. Structural parameters (`distance`, `M`, `efConstruction`, `quantization`) do rebuild the index when changed.
200
- - With `quantization: "int8"`, nearest-neighbor `sort` queries re-rank results against full-precision vectors, restoring exact ordering and exact `$distance` values. Distance-threshold (`lt`/`le`) queries filter on the approximate distance.
201
- - The correct parameter name is `efConstruction` (seeds the construction budget) and `efConstructionSearch` (controls search budget). The name `efSearchConstruction` is a previous documentation error.
202
- - When no `ef` is passed and `efConstructionSearch` (or `efConstruction`) is not explicitly set, the search budget auto-scales with index size.
203
- - `cosine` is the default distance function when `distance` is not specified.
208
+ - `vectorFilter` is available from the JavaScript API only — it cannot be expressed in a REST query string. It must be synchronous, side-effect free, and fast. Verdicts are memoized per query.
209
+ - `rowFilter` is also JavaScript API only. It participates in HNSW traversal so callers receive the k nearest _matching_ records. It does not apply to direct primary-key `get` calls. Prefer indexed query conditions for predicates that can be expressed declaratively.
210
+ - When a query passes no `ef` and the index does not explicitly configure `efConstructionSearch` (or `efConstruction`), the search budget auto-scales with index size.
211
+ - Distance-threshold (`lt`/`le`) queries with `quantization: "int8"` filter on approximate distance, not re-ranked full-precision distance.
212
+ - `$distance` is available in both `sort`-based ranking and `conditions`-based threshold queries.