@harperfast/template-vue-studio 1.13.5 → 1.13.7

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 +2 -2
@@ -14,31 +14,35 @@ metadata:
14
14
  reference/v5/resources/resource-api.md#`addTo(property: string, value:
15
15
  number)`
16
16
  - reference/v5/components/javascript-environment.md#Module Formats
17
- sourceCommit: 6c3e29dd9149201364b0d74642725c30f0305e3e
18
- inputHash: b42fe5775d69e9a2
17
+ sourceCommit: 0a29827da61afe7fff40ee8de87e1d4c2c286bea
18
+ inputHash: 4f4e5f98986aef68
19
19
  ---
20
20
 
21
21
  # Programmatic Table Requests
22
22
 
23
- Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
23
+ Instructions for the agent to interact with Harper tables programmatically using the `tables` object, including querying, transactions, and module setup.
24
24
 
25
25
  **Instead of:** ORM and query-builder clients (Prisma, Drizzle, Knex). Use this rule rather than adding that service. See `harper-architecture`.
26
26
 
27
27
  ## When to Use
28
28
 
29
- Apply this rule when writing server-side Harper code that reads, writes, searches, or transactionally modifies table data through the `tables` object. Use it when building background jobs, SSR renderers, or any code that calls `search(`, `addTo`, `select`, `sort`, or `transaction()` directly rather than through REST endpoints.
29
+ Apply this rule when writing server-side Harper code that reads or writes table data directly — for example, in request handlers, background jobs, timers, or SSR entry points. Use it whenever you need to construct a query with `conditions`, `sort`, `select`, `limit`, or `offset`, or when you need to wrap writes in a `transaction()`.
30
30
 
31
31
  ## How It Works
32
32
 
33
- 1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. This is equivalent to `databases.data.<TableName>`.
33
+ 1. **Import `tables` (and other APIs) from `harper`**: Access tables defined in `schema.graphql` via the `tables` object. Each table is a property matching its type name.
34
34
 
35
35
  ```javascript
36
- import { tables, Resource } from 'harper';
36
+ import { tables, transaction } from 'harper';
37
37
  const { Product } = tables;
38
- // same as: databases.data.Product
38
+ // equivalent to: databases.data.Product
39
39
  ```
40
40
 
41
- CommonJS is also supported: `const { tables, Resource } = require('harper');`
41
+ For CommonJS:
42
+
43
+ ```javascript
44
+ const { tables, Resource } = require('harper');
45
+ ```
42
46
 
43
47
  For components in their own directory, link the package first:
44
48
 
@@ -46,16 +50,9 @@ Apply this rule when writing server-side Harper code that reads, writes, searche
46
50
  npm link harper
47
51
  ```
48
52
 
49
- When bundling for SSR with Vite, keep `harper` external so it resolves to the runtime:
53
+ When bundling for SSR with Vite, keep `harper` external so it resolves to the runtime — add `ssr: { external: ['harper'] }` in `vite.config`.
50
54
 
51
- ```javascript
52
- // vite.config
53
- ssr: {
54
- external: ['harper'];
55
- }
56
- ```
57
-
58
- 2. **Define your schema with `@table` (and `@indexed` where needed)**: Tables must be declared in `schema.graphql`. Mark attributes that will be used as sort keys or standalone condition attributes with `@indexed`.
55
+ 2. **Define your schema with `@table`**: Every type you want to access via `tables` must be declared with `@table` in `schema.graphql`. Use `@indexed` on attributes you intend to sort or filter by efficiently.
59
56
 
60
57
  ```graphql
61
58
  type Product @table {
@@ -65,54 +62,88 @@ Apply this rule when writing server-side Harper code that reads, writes, searche
65
62
  }
66
63
  ```
67
64
 
68
- 3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable; iterate the result with `for await`. Use a `conditions` array to filter records. Each condition specifies `attribute`, `value`, and an optional `comparator`.
65
+ 3. **Perform basic CRUD operations**: Use the table class methods directly.
66
+
67
+ ```javascript
68
+ // Create
69
+ const created = await Product.create({ name: 'Shirt', price: 9.5 });
69
70
 
70
- | Property | Description |
71
- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72
- | `attribute` | Property name, or array for chained/joined properties |
73
- | `value` | The value to match |
74
- | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal`, or a full-text comparator |
75
- | `conditions` | Nested conditions array |
76
- | `operator` | `and` (default) or `or` for the nested `conditions` |
71
+ // Patch
72
+ await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
73
+
74
+ // Get by primary key
75
+ const record = await Product.get(created.id);
76
+ ```
77
+
78
+ 4. **Query with `search(` and a query object**: Pass a query object with `conditions`, `sort`, `limit`, `offset`, `select`, and other options. `search(` returns an async iterable. If order doesn't matter, omit `sort` entirely and `search({})` will iterate without an index requirement.
77
79
 
78
80
  ```javascript
79
- for await (const record of Product.search({
81
+ const query = {
80
82
  conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
81
- })) {
83
+ };
84
+ for await (const record of Product.search(query)) {
82
85
  // process record
83
86
  }
84
87
  ```
85
88
 
86
- 4. **Use `select` to control which properties are returned**: Pass an array of property names, a string for a single property, or nested objects for relationships.
89
+ 5. **Build `conditions` arrays**: Each condition object supports the following properties:
90
+
91
+ | Property | Description |
92
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
+ | `attribute` | Property name, or array for chained/joined properties |
94
+ | `value` | The value to match |
95
+ | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal`, or a full-text comparator (`matches`, `matches_all`, `matches_phrase`, `matches_prefix`, `matches_fuzzy`, `matches_fuzzy_prefix`, and their `not_` forms) |
96
+ | `conditions` | Nested conditions array |
97
+ | `operator` | `and` (default) or `or` for nested `conditions` |
98
+ | `fields` | Full-text source fields to search; every name must belong to the selected full-text index |
99
+ | `includeHighlights` | Include configured full-text highlights |
100
+ | `maxIndexLagMilliseconds` | Maximum accepted full-text index lag |
101
+ | `waitForIndexMilliseconds` | Time to wait for acceptable full-text coverage |
102
+
103
+ Use nested `conditions` and `operator` for compound logic:
87
104
 
88
105
  ```javascript
89
- const book = await Book.get({
90
- id: 42,
91
- select: ['id', 'title', { name: 'author', select: ['name'] }],
106
+ Product.search({
107
+ conditions: [
108
+ { attribute: 'price', comparator: 'less_than', value: 100 },
109
+ {
110
+ operator: 'or',
111
+ conditions: [
112
+ { attribute: 'rating', comparator: 'greater_than', value: 4 },
113
+ { attribute: 'featured', value: true },
114
+ ],
115
+ },
116
+ ],
92
117
  });
93
118
  ```
94
119
 
95
- Special `select` properties:
96
- - `$id` — returns the primary key regardless of its name
97
- - `$updatedtime` — returns the last-updated timestamp
98
- - `$distance` — returns computed vector distance when using a vector index
99
- - `$score` — returns BM25 relevance score for full-text queries
100
- - `$highlights` — returns full-text fragments and matching spans
101
-
102
- 5. **Use `sort` with an `@indexed` attribute or combine with `conditions`**: Harper requires either an `@indexed` sort attribute or at least one `conditions` entry when sorting. Sorting by a non-indexed attribute with zero conditions raises:
120
+ Use an array `attribute` to traverse relationships:
103
121
 
104
- > `HdbError: <attribute> is not indexed and not combined with any other conditions`
122
+ ```javascript
123
+ Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
124
+ ```
105
125
 
106
- Note: `@primaryKey` alone is treated as not indexed for sort purposes. To iterate a whole table in primary-key order, add an open-ended condition:
126
+ 6. **Apply `select` to shape results**: Pass an array of property names, nested objects for relationships, or a string for a single property.
107
127
 
108
128
  ```javascript
109
- Product.search({
110
- conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
111
- sort: { attribute: 'id' },
129
+ // Flat select
130
+ Product.search({ select: ['name', 'price'] });
131
+
132
+ // Nested relationship select
133
+ const book = await Book.get({
134
+ id: 42,
135
+ select: ['id', 'title', { name: 'author', select: ['name'] }],
112
136
  });
137
+
138
+ // Special properties:
139
+ // $id — primary key regardless of name
140
+ // $updatedtime — last-updated timestamp
141
+ // $distance — vector index distance
142
+ // $score — full-text BM25 score
143
+ // $highlights — full-text highlight fragments
113
144
  ```
114
145
 
115
- `sort` object properties:
146
+ 7. **Use `sort` with `@indexed` attributes**: Provide a `sort` object with `attribute`, optional `descending`, and optional `next` for tie-breaking.
116
147
 
117
148
  | Property | Description |
118
149
  | ------------ | ---------------------------------------------------------- |
@@ -120,102 +151,137 @@ Apply this rule when writing server-side Harper code that reads, writes, searche
120
151
  | `descending` | Sort descending if `true` (default: `false`) |
121
152
  | `next` | Secondary sort to resolve ties (same structure) |
122
153
 
123
- 6. **Apply `limit` and `offset` for pagination**: Add these to the Query object to bound result sets.
124
-
125
154
  ```javascript
155
+ // attribute must be @indexed, or at least one condition must be present
126
156
  Product.search({
127
- conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
128
- limit: 20,
129
- offset: 40,
157
+ sort: { attribute: 'price', descending: true },
130
158
  });
131
159
  ```
132
160
 
133
- 7. **Use `explain` and `enforceExecutionOrder` for debugging and optimization**:
134
- - `explain: true` — returns conditions reordered as Harper will execute them.
135
- - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling Harper's automatic re-ordering.
161
+ If the sort `attribute` is not `@indexed` and no `conditions` are present, Harper throws:
162
+
163
+ > `HdbError: <attribute> is not indexed and not combined with any other conditions`
136
164
 
137
- 8. **Use `addTo` for concurrent-safe numeric updates**: Increments or decrements a property using CRDT incrementation, safe across threads and nodes.
165
+ To iterate a whole table in primary-key order, add an open-ended condition:
138
166
 
139
167
  ```javascript
140
- static async post(target, data) {
141
- const record = await this.update(target.id);
142
- record.addTo('quantity', -1); // decrement safely across nodes
143
- }
168
+ Product.search({
169
+ conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
170
+ sort: { attribute: 'id' },
171
+ });
144
172
  ```
145
173
 
146
- 9. **Wrap background or timer work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural request context. Always `await` the call and `catch` errors.
174
+ 8. **Apply `limit` and `offset` for pagination**:
147
175
 
148
176
  ```javascript
149
- await transaction(async (txn) => {
150
- for (let item of data) {
151
- await MyTable.put(item, txn);
152
- }
177
+ Product.search({
178
+ conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
179
+ sort: { attribute: 'price' },
180
+ limit: 20,
181
+ offset: 40,
153
182
  });
154
183
  ```
155
184
 
156
- The `txn` object exposes:
157
-
158
- | Member | Type | Description |
159
- | --------------------- | --------------- | ------------------------------------------------------ |
160
- | `commit()` | `() => Promise` | Commits the current transaction |
161
- | `abort()` | `() => void` | Aborts the transaction and resets it |
162
- | `resetReadSnapshot()` | `() => void` | Resets the read snapshot to the latest committed state |
163
- | `timestamp` | `number` | Timestamp associated with the current transaction |
185
+ 9. **Use `explain` and `enforceExecutionOrder` for debugging and control**:
186
+ - Set `explain: true` to return conditions reordered as Harper will execute them.
187
+ - Set `enforceExecutionOrder: true` to force conditions to execute in the order supplied, disabling Harper's automatic reordering.
164
188
 
165
- On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
189
+ ```javascript
190
+ Product.search({
191
+ conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
192
+ explain: true,
193
+ });
194
+ ```
166
195
 
167
- 10. **Understand atomicity boundaries**: All tables within the same database share a single transactional context — reads return a consistent snapshot and writes are committed atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
196
+ 10. **Use `addTo` for concurrent-safe numeric updates**: `addTo(property, value)` uses CRDT incrementation, safe across threads and nodes.
197
+
198
+ ```javascript
199
+ static async post(target, data) {
200
+ const record = await this.update(target.id);
201
+ record.addTo('quantity', -1); // decrement safely across nodes
202
+ }
203
+ ```
204
+
205
+ 11. **Wrap out-of-context writes in `transaction()`**: HTTP request handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
206
+
207
+ ```javascript
208
+ import { isMainThread } from 'node:worker_threads';
209
+ import { tables, transaction } from 'harper';
210
+ const { MyTable } = tables;
211
+
212
+ if (isMainThread) {
213
+ let running = false;
214
+ setInterval(async () => {
215
+ if (running) return; // the previous run has not committed yet
216
+ running = true;
217
+ try {
218
+ let data = await (await fetch('https://example.com/data')).json();
219
+ await transaction(async (txn) => {
220
+ for (let item of data) {
221
+ await MyTable.put(item, txn);
222
+ }
223
+ });
224
+ } catch (error) {
225
+ logger.error('hourly import failed', error);
226
+ } finally {
227
+ running = false;
228
+ }
229
+ }, 3600000);
230
+ }
231
+ ```
232
+
233
+ - Always `await` the `transaction()` call and `catch` it.
234
+ - Guard against overlap with a `running` flag when a job can outlast its interval.
235
+
236
+ 12. **Understand `transaction()` atomicity and scope**: Transactions span a single database. All tables within the same database share one transactional context — reads return a consistent snapshot and writes across multiple tables commit with atomicity. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
237
+
238
+ The `txn` object received by the callback exposes:
239
+
240
+ | Member | Type | Description |
241
+ | --------------------- | --------------- | ------------------------------------------------------ |
242
+ | `commit()` | `() => Promise` | Commits the current transaction |
243
+ | `abort()` | `() => void` | Aborts the transaction and resets it |
244
+ | `resetReadSnapshot()` | `() => void` | Resets the read snapshot to the latest committed state |
245
+ | `timestamp` | `number` | Timestamp associated with the current transaction |
246
+
247
+ On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
168
248
 
169
249
  ## Examples
170
250
 
171
- ### Basic CRUD and search
251
+ **Relationship group — one related record must meet all conditions:**
172
252
 
173
253
  ```javascript
174
- import { tables } from 'harper';
175
- const { Product } = tables;
176
-
177
- // Create
178
- const created = await Product.create({ name: 'Shirt', price: 9.5 });
179
-
180
- // Patch
181
- await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
182
-
183
- // Get by primary key
184
- const record = await Product.get(created.id);
185
-
186
- // Search with conditions
187
- const query = {
188
- conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
189
- };
190
- for await (const record of Product.search(query)) {
191
- // process record
192
- }
193
- ```
194
-
195
- ### Nested conditions with `or`
196
-
197
- ```javascript
198
- Product.search({
254
+ const brands = [];
255
+ for await (const brand of Brand.search({
199
256
  conditions: [
200
- { attribute: 'price', comparator: 'less_than', value: 100 },
201
257
  {
202
- operator: 'or',
258
+ attribute: 'products',
203
259
  conditions: [
204
- { attribute: 'rating', comparator: 'greater_than', value: 4 },
205
- { attribute: 'featured', value: true },
260
+ { attribute: 'name', value: 'Keyboard' },
261
+ { attribute: 'price', comparator: 'greater_than_equal', value: 30 },
206
262
  ],
207
263
  },
208
264
  ],
209
- });
265
+ select: ['id', 'name', { name: 'products', select: ['name', 'price'] }],
266
+ })) {
267
+ brands.push(brand);
268
+ }
210
269
  ```
211
270
 
212
- ### Chained attribute reference (join/relationship)
271
+ **SSR entry point reading directly from Harper:**
213
272
 
214
273
  ```javascript
215
- Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
274
+ import { tables } from 'harper';
275
+
276
+ export async function render(url: string): Promise<string> {
277
+ const product = await tables.Product.get(idFromUrl(url));
278
+ return renderToString(/* <App product={product} /> */);
279
+ }
216
280
  ```
217
281
 
218
- ### Selecting and constraining related records
282
+ Keep `harper` external in `vite.config` — e.g. `ssr: { external: ['harper'] }` — so it resolves to the runtime instead of being bundled.
283
+
284
+ **Nested relationship select with constraints:**
219
285
 
220
286
  ```javascript
221
287
  const brand = await Brand.get({
@@ -234,57 +300,20 @@ const brand = await Brand.get({
234
300
  });
235
301
  ```
236
302
 
237
- ### Background job with `transaction()`
238
-
239
- ```javascript
240
- import { isMainThread } from 'node:worker_threads';
241
- import { tables, transaction } from 'harper';
242
- const { MyTable } = tables;
243
-
244
- if (isMainThread) {
245
- let running = false;
246
- setInterval(async () => {
247
- if (running) return; // the previous run has not committed yet
248
- running = true;
249
- try {
250
- let data = await (await fetch('https://example.com/data')).json();
251
- await transaction(async (txn) => {
252
- for (let item of data) {
253
- await MyTable.put(item, txn);
254
- }
255
- });
256
- } catch (error) {
257
- logger.error('hourly import failed', error);
258
- } finally {
259
- running = false;
260
- }
261
- }, 3600000); // every hour
262
- }
263
- ```
264
-
265
- ### SSR with Vite
266
-
267
- ```typescript
268
- import { tables } from 'harper';
269
-
270
- export async function render(url: string): Promise<string> {
271
- const product = await tables.Product.get(idFromUrl(url));
272
- return renderToString(/* <App product={product} /> */);
273
- }
274
- ```
275
-
276
- Keep `harper` external in `vite.config` so it resolves to the runtime:
303
+ **Sort with secondary tie-breaker across a relationship:**
277
304
 
278
305
  ```javascript
279
- ssr: {
280
- external: ['harper'];
281
- }
306
+ Brand.search({
307
+ conditions: [{ attribute: ['products', 'price'], comparator: 'greater_than_equal', value: 30 }],
308
+ sort: { attribute: ['products', 'name'], next: { attribute: 'id' } },
309
+ });
282
310
  ```
283
311
 
284
312
  ## Notes
285
313
 
286
- - Calls through `tables` run in a trusted server-side context and do **not** automatically apply the target table's role permissions. Set `checkPermission: true` on the query and pass the authenticated `context` as the second argument when authorization is required.
287
- - `update`, `patch`, and `delete` operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
288
- - Pass `allowFullScan: true` to permit an unconditional ordered scan without conditions. If order doesn't matter, omit `sort` entirely — `search({})` iterates without an index requirement.
289
- - If `transaction()` is called with a context that already has an active transaction, it reuses that transaction and executes the callback immediately — safe to call defensively.
290
- - Guard timer-based jobs against overlap: a timer fires on schedule regardless of whether the previous run has committed. Use a `running` flag to skip a tick when the previous run is still active.
314
+ - Calls through `tables` and `databases` run in a trusted server-side context and do not automatically apply the target table's role permissions. To enforce authorization, set `checkPermission: true` on the query and pass the authenticated `context` as the second argument to `search()` or `get()`. Harper then authorizes the read using `context.user`, including table, selected-property, and full-text source-field permissions.
315
+ - Programmatic `update`, `patch`, and `delete` calls operate directly on stored (potentially live production) data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
316
+ - `transaction()` is safe to call defensively: if the context already has an active transaction, it reuses it and executes the callback immediately.
317
+ - `resetReadSnapshot()` on the `txn` object resets the read snapshot to the latest committed state mid-transaction.
318
+ - The bare `@primaryKey` is treated as not indexed for sort purposes (it uses the primary store, not a secondary index). Sorting by primary key alone with no `conditions` triggers the `HdbError: <attribute> is not indexed and not combined with any other conditions` error. Add an open-ended condition or pass `allowFullScan: true` to permit an unconditional scan.
319
+ - All installed components have `harper` automatically linked. For components in their own directory, run `npm link harper` manually.