@harperfast/template-vue-studio 1.13.6 → 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
@@ -9,37 +9,43 @@ metadata:
9
9
  - reference/v5/database/schema.md#Overview
10
10
  - reference/v5/database/schema.md#Type Directives
11
11
  - reference/v5/database/schema.md#Field Directives
12
- sourceCommit: 4aea8b1fffc53ee1dcf4841676350fef58f24056
13
- inputHash: af9e326b0cf010d8
12
+ sourceCommit: e4a7bd899e1a68a83d9ed1d770ec73569fabc260
13
+ inputHash: 16a9e0488c853439
14
14
  ---
15
15
 
16
16
  # Schema Design and GraphQL Tooling
17
17
 
18
- Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
18
+ Instructions for the agent to follow when designing Harper database schemas using GraphQL type definitions, core directives, and tooling configuration.
19
19
 
20
20
  ## When to Use
21
21
 
22
- Apply this rule when creating or modifying Harper schema files, configuring `graphqlSchema` in `config.yaml`, or deciding which directives to apply to tables and fields. Use it whenever a task involves defining tables, primary keys, indexes, or export behavior.
22
+ Apply this rule when creating or modifying Harper schema files — defining tables, primary keys, indexes, and export behavior. Use it when configuring `graphqlSchema` in `config.yaml` or when choosing directives to control table structure, access patterns, and record lifecycle.
23
23
 
24
24
  ## How It Works
25
25
 
26
- 1. **Load the schema via `graphqlSchema`**: In the component's `config.yaml`, point to the schema file:
26
+ 1. **Create a schema file** using standard GraphQL type definitions with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
27
+
28
+ ```graphql
29
+ type Dog @table {
30
+ id: Long @primaryKey
31
+ name: String
32
+ breed: String
33
+ age: Int
34
+ }
35
+ ```
36
+
37
+ 2. **Register the schema** in the component's `config.yaml` using the `graphqlSchema` plugin:
27
38
 
28
39
  ```yaml
29
40
  graphqlSchema:
30
41
  files: 'schema.graphql'
31
42
  ```
32
43
 
33
- Both plugins and applications can specify schemas. The schema ensures required tables exist on deployment, enforces types, controls indexing, and defines relationships.
34
-
35
- 2. **Mark tables with `@table`**: Apply `@table` to every GraphQL type that should become a Harper database table. The type name becomes the table name by default.
44
+ 3. **Mark every table type with `@table`**. This tells Harper to create and manage the table. The type name becomes the table name by default.
36
45
 
37
46
  ```graphql
38
- type Dog @table {
47
+ type MyTable @table {
39
48
  id: Long @primaryKey
40
- name: String
41
- breed: String
42
- age: Int
43
49
  }
44
50
  ```
45
51
 
@@ -53,13 +59,15 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
53
59
  | `eviction` | `Int` | `0` | Additional seconds after `expiration` before physical removal |
54
60
  | `scanInterval` | `Int` | `(expiration + eviction) / 4` | Seconds between eviction scans |
55
61
  | `replicate` | `Boolean` | `true` | Enable replication of this table |
56
- | `replicaExpiration` | `Float` | `3600` | Seconds a record fetched from another node is kept as a local replica |
62
+ | `replicaExpiration` | `Float` | `3600` | Seconds to keep a local residency replica |
57
63
  | `replicaRefreshFraction` | `Float` | `0.5` | Fraction of `replicaExpiration` after which a read renews the replica lifetime |
58
64
  | `audit` | `Boolean` | `logging.auditLog` | Enable the table's transaction log |
59
65
  | `cacheControl` | `String` | — | `Cache-Control` header for anonymous GET/HEAD 200/304 responses |
60
66
  | `randomAccessFields` | `Boolean` | `storage.randomAccessFields` | Pin this table's record encoding |
61
67
 
62
- 3. **Designate a primary key with `@primaryKey`**: Apply `@primaryKey` to exactly one field per table. Primary keys must be unique; duplicate inserts are rejected.
68
+ 4. **Designate a primary key with `@primaryKey`** on exactly one field per table. Primary keys must be unique; duplicate inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
69
+ - `String` or `ID` → UUID string
70
+ - `Int`, `Long`, or `Any` → auto-incrementing integer
63
71
 
64
72
  ```graphql
65
73
  type Product @table {
@@ -68,13 +76,9 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
68
76
  }
69
77
  ```
70
78
 
71
- If no primary key is provided on insert, Harper auto-generates one:
72
- - **UUID string** — when type is `String` or `ID`
73
- - **Auto-incrementing integer** — when type is `Int`, `Long`, or `Any`
74
-
75
- Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
79
+ Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
76
80
 
77
- 4. **Index queryable fields with `@indexed`**: Apply `@indexed` to any field that must be filterable via REST queries, SQL, or NoSQL operations.
81
+ 5. **Add `@indexed` to fields that need fast querying**. Required for filtering by an attribute in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
78
82
 
79
83
  ```graphql
80
84
  type Product @table {
@@ -84,9 +88,7 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
84
88
  }
85
89
  ```
86
90
 
87
- If the field value is an array, each element is individually indexed. Null values are indexed by default.
88
-
89
- 5. **Expose tables externally with `@export`**: Apply `@export` to make a table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment.
91
+ 6. **Expose the table externally with `@export`**. This makes the table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment; without it, the type name is used.
90
92
 
91
93
  ```graphql
92
94
  type MyTable @table @export(name: "my-table") {
@@ -94,9 +96,9 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
94
96
  }
95
97
  ```
96
98
 
97
- `@export` alone does not serve HTTP traffic — REST must also be enabled for the application via `rest: true` in `config.yaml` or Harper's built-in default. `@export` is a routing directive, not access control: omitting it returns 404 to callers but the table remains accessible through the Operations API and SQL.
99
+ `@export` alone does not serve HTTP traffic — REST must also be enabled for the application, either with `rest: true` in `config.yaml` or by Harper's built-in default for a component with no configuration file.
98
100
 
99
- 6. **Prevent extra properties with `@sealed`** (when needed): Apply `@sealed` to reject records that include properties beyond those declared in the schema. By default, Harper allows additional properties.
101
+ 7. **Use `@sealed` to prevent extra properties** on records beyond those declared in the schema. By default, Harper allows records to have additional properties.
100
102
 
101
103
  ```graphql
102
104
  type StrictRecord @table @sealed {
@@ -105,33 +107,13 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
105
107
  }
106
108
  ```
107
109
 
108
- 7. **Use unique database names for plugins and applications**: All tables default to the `data` database. Specify a distinct `database` argument on `@table` to avoid naming collisions between components.
109
-
110
- 8. **Apply timestamp and expiration field directives** where needed:
111
- - `@createdTime` — auto-assigns a Unix epoch millisecond timestamp on record creation.
112
- - `@updatedTime` — auto-assigns a Unix epoch millisecond timestamp on each update.
113
- - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); overrides the table-level `expiration` default.
114
- - `@hidden` — suppresses the type or field from MCP tool descriptors and the OpenAPI document. Does not restrict data access.
115
-
116
- ```graphql
117
- type Event @table {
118
- id: Long @primaryKey
119
- createdAt: Long @createdTime
120
- updatedAt: Long @updatedTime
121
- }
122
-
123
- type Session @table {
124
- id: ID @primaryKey
125
- token: String
126
- expiresAt: Long @expiresAt
127
- }
128
- ```
129
-
130
- Key `@expiresAt` behaviors:
131
- - Takes an absolute Unix epoch millisecond timestamp, not a duration. A full-record `put` that omits the field clears it; a `patch` preserves it.
132
- - A per-record value may extend or shorten a record's expiration relative to the table-level `expiration` default. When a record omits the field, the table default (if any) applies.
110
+ 8. **Use timestamp directives** to auto-populate lifecycle fields:
111
+ - `@createdTime` — assigns Unix epoch milliseconds on record creation
112
+ - `@updatedTime` — assigns Unix epoch milliseconds on every update
113
+ - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); authoritative over the table-level `expiration` default
133
114
 
134
115
  9. **Use `@embed`** to automatically compute an embedding vector for an attribute whenever the source field is written (requires `source` and `model` arguments; field type must be `[Float]`):
116
+
135
117
  ```graphql
136
118
  type Document @table {
137
119
  id: Long @primaryKey
@@ -139,11 +121,12 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
139
121
  embedding: [Float] @embed(source: "text", model: "default")
140
122
  }
141
123
  ```
142
- The attribute is automatically indexed with an HNSW vector index. A failure to compute the embedding fails the write. An update that does not touch the `source` field leaves the vector unchanged. Setting the `source` field to `null` sets the vector to `null`.
124
+
125
+ 10. **Use unique `database` names** in plugins or applications to avoid table naming collisions, since all tables default to the `data` database.
143
126
 
144
127
  ## Examples
145
128
 
146
- **Minimal schema with two tables:**
129
+ **Minimal two-table schema:**
147
130
 
148
131
  ```graphql
149
132
  type Dog @table {
@@ -159,7 +142,17 @@ type Breed @table {
159
142
  }
160
143
  ```
161
144
 
162
- **Caching table with expiration, eviction, and scan tuning:**
145
+ **Table with name override and specific database:**
146
+
147
+ ```graphql
148
+ type Product @table(table: "products", database: "commerce") {
149
+ id: Long @primaryKey
150
+ name: String @indexed
151
+ price: Float @indexed
152
+ }
153
+ ```
154
+
155
+ **Caching table with expiration and eviction tuning:**
163
156
 
164
157
  ```graphql
165
158
  # Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
@@ -179,16 +172,7 @@ type Product @table(cacheControl: "public, max-age=60") @export {
179
172
  }
180
173
  ```
181
174
 
182
- **Table in a named database with expiration:**
183
-
184
- ```graphql
185
- type Event @table(database: "analytics", expiration: 86400) {
186
- id: Long @primaryKey
187
- name: String @indexed
188
- }
189
- ```
190
-
191
- **Replica lifetime tuning:**
175
+ **Table with replica lifetime control:**
192
176
 
193
177
  ```graphql
194
178
  # Keep fetched records for a day; a read after six hours renews them
@@ -198,18 +182,19 @@ type Order @table(replicaExpiration: 86400, replicaRefreshFraction: 0.25) {
198
182
  }
199
183
  ```
200
184
 
201
- **Random-access field encoding pinned on the table:**
185
+ **Session table with per-record expiration and timestamps:**
202
186
 
203
187
  ```graphql
204
- type Reading @table(randomAccessFields: true) {
188
+ type Session @table {
205
189
  id: ID @primaryKey
206
- sensorId: String @indexed
207
- celsius: Float
208
- recordedAt: Int
190
+ userId: String @indexed
191
+ createdAt: Long @createdTime
192
+ updatedAt: Long @updatedTime
193
+ expiresAt: Long @expiresAt
209
194
  }
210
195
  ```
211
196
 
212
- **`config.yaml` loading the schema:**
197
+ **`config.yaml` registration:**
213
198
 
214
199
  ```yaml
215
200
  graphqlSchema:
@@ -218,12 +203,10 @@ graphqlSchema:
218
203
 
219
204
  ## Notes
220
205
 
221
- - Schemas are flexible by default — records may include additional properties. Use `@sealed` to prevent this.
222
- - `@export` is a routing directive, not an access control mechanism. Use RBAC and `attribute_permissions` to restrict data access.
223
- - `cacheControl` on `@table` only emits the header for anonymous (unauthenticated) GET/HEAD 200/304 responses. Authenticated responses always receive `Cache-Control: private, no-cache`.
224
- - `expiration`, `eviction`, and `scanInterval` work together: `expiration` marks a record stale, `eviction` controls physical removal, and `scanInterval` sets how often the sweep runs. Eviction scans are clock-aligned to the server's local timezone, not startup-aligned.
225
- - Eviction removes non-indexed record data but does not remove a record from its secondary indexes; indexes remain functional for evicted records.
226
- - `replicaExpiration` and `replicaRefreshFraction` apply only on the RocksDB engine. On LMDB, remote reads remain proxy reads regardless of these settings.
206
+ - `@export` is a routing directive, not access control. Omitting it returns 404 to callers but does not protect the data — the table remains accessible through the Operations API and SQL. Use RBAC role grants and `attribute_permissions` for actual access control.
207
+ - `@hidden` (on types or fields) suppresses entries from MCP tool descriptors and the OpenAPI document only. It does not restrict data access. Use `attribute_permissions` on roles for field-level enforcement.
208
+ - Null values are indexed by default for `@indexed` fields, enabling queries like `GET /Product/?category=null`. This matches records that store `null`, not records that omit the attribute.
209
+ - `cacheControl` emits the header only on anonymous (unauthenticated) GET/HEAD 200/304 responses. Authenticated responses receive `Cache-Control: private, no-cache` regardless of the declaration.
210
+ - A `patch` of other fields preserves an existing `@expiresAt` value; a full `put` that omits the field clears it. Always re-include `expiresAt` in session-renewal writes.
211
+ - `replicaExpiration` and `randomAccessFields` apply to RocksDB only. LMDB tables ignore replica behavior regardless of settings.
227
212
  - Disabling replication on a table (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
228
- - `randomAccessFields` on `@table` pins the encoding when the table is created. Editing the argument later does not repin an existing table.
229
- - `@hidden` is a metadata-visibility directive only — it does not restrict data access. Use `attribute_permissions` on roles for field-level access control.
@@ -7,17 +7,17 @@ metadata:
7
7
  mode: generate
8
8
  sources:
9
9
  - release-notes/v5-lincoln/v5-migration.md
10
- sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
11
- inputHash: 66ca7a9e265d006e
10
+ sourceCommit: 62139d5475bb9993c3aa6bc8d23420ea7610f739
11
+ inputHash: 141693224b082d1c
12
12
  ---
13
13
 
14
14
  # v5 Upgrade: Breaking Changes and Migration Guide
15
15
 
16
- Instructions for the agent to follow when migrating a Harper application to v5, covering all breaking changes and required code updates.
16
+ Instructions for the agent to apply when migrating a Harper application to v5, covering all breaking changes and required code updates.
17
17
 
18
18
  ## When to Use
19
19
 
20
- Apply this rule when upgrading an existing Harper application from v4 to v5, when encountering runtime errors after upgrading, or when reviewing application code for v5 compatibility. Every breaking change listed here must be addressed before the application will behave correctly under v5.
20
+ Apply this rule when upgrading an existing Harper application from v4 to v5, when encountering runtime errors related to module loading, transactions, record access, or process spawning after a v5 upgrade, or when scaffolding new v5-compatible application code.
21
21
 
22
22
  ## How It Works
23
23
 
@@ -27,12 +27,12 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
27
27
  import { tables } from 'harper';
28
28
  ```
29
29
 
30
- 2. **Enable install scripts if needed**: Harper v5 runs `npm install` with `--ignore-scripts` by default. If your application requires install scripts (e.g., to compile native binaries), set `allowInstallScripts` in your deployment options.
30
+ 2. **Enable install scripts if needed**: Harper v5 runs `npm install` with `--ignore-scripts` by default. If your application requires install scripts (e.g., to install native binaries), set `allowInstallScripts` in your deployment options.
31
31
 
32
- 3. **Update `Table.get` usage**: `Table.get` now returns a plain frozen record object, not a table class instance. The `wasLoadedFromSource()` method no longer exists on the returned object. Replace it with `loadedFromSource` on the `RequestTarget`:
32
+ 3. **Update `Table.get` usage**: `Table.get` now returns a plain frozen record object, not a table class instance. The `wasLoadedFromSource()` method no longer exists on the returned record. Use a `RequestTarget` and check `loadedFromSource` on the target instead.
33
33
 
34
34
  ```javascript
35
- // Before
35
+ // Before (v4):
36
36
  const record = await Table.get(id);
37
37
  if (record.wasLoadedFromSource()) {
38
38
  // record was loaded from origin (not cache)
@@ -40,8 +40,7 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
40
40
  ```
41
41
 
42
42
  ```javascript
43
- // After
44
- import { getContext } from 'harper';
43
+ // After (v5):
45
44
  const target = new RequestTarget();
46
45
  target.id = id;
47
46
  const record = await Table.get(target);
@@ -50,34 +49,23 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
50
49
  }
51
50
  ```
52
51
 
53
- The record objects do have `getUpdatedTime` and `getExpiresAt` methods available.
52
+ The record objects still expose `getUpdatedTime` and `getExpiresAt` methods.
54
53
 
55
- 4. **Handle frozen records**: The record object returned by `Table.get` is frozen — you cannot mutate it directly. Copy it before modifying:
54
+ 4. **Handle frozen records**: Records returned by `Table.get` are frozen — you cannot mutate them directly. Spread into a new object instead.
56
55
 
57
56
  ```javascript
58
- // Before
57
+ // Before (v4):
59
58
  const record = await Table.get(id);
60
59
  record.property = 'changed';
61
60
  ```
62
61
 
63
62
  ```javascript
64
- // After
63
+ // After (v5):
65
64
  let record = await Table.get(id);
66
65
  record = { ...record, property: 'changed' };
67
66
  ```
68
67
 
69
- 5. **Register allowed spawn commands via `allowedSpawnCommands`**: `spawn` and `execFile` may only launch executables listed in `applications.allowedSpawnCommands` in `harper-config.yaml`. Only the first token of the command is matched. `exec` is not usable through the substituted module, and `execSync` always throws.
70
-
71
- ```yaml
72
- applications:
73
- allowedSpawnCommands:
74
- - npm
75
- - node
76
- ```
77
-
78
- Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
79
-
80
- 6. **Update transaction and context usage**: Harper v5 uses asynchronous context tracking. `Table.get` and other calls now automatically inherit the current transaction. Code that previously omitted context to bypass a transaction will no longer work as expected. Explicitly commit the transaction or wrap calls in a new transaction to read updated data:
68
+ 5. **Update transaction and context usage**: Harper v5 uses asynchronous context tracking. `Table.get` and other table calls now automatically inherit the current transaction. If your code previously omitted context to bypass a transaction and read the latest data, that workaround no longer works. Explicitly commit the transaction and/or wrap reads in a new transaction using `getContext` and `transaction` from `'harper'`.
81
69
 
82
70
  ```javascript
83
71
  import { setTimeout as delay } from 'node:timers/promises';
@@ -94,47 +82,45 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
94
82
  }
95
83
  ```
96
84
 
97
- Use `getContext` (exported from `'harper'`) to access the current transaction anywhere without passing context explicitly.
85
+ 6. **Register allowed spawn commands**: Spawning child processes via `node:child_process` is now restricted. Only executables listed in `applications.allowedSpawnCommands` in `harper-config.yaml` may be spawned. Additionally, `spawn`, `execFile`, and `fork` require a `name` property in the `options` argument to prevent process multiplication across threads. `exec` is not usable through the substituted module, and `execSync` always throws.
98
86
 
99
- 7. **Replace `blob.save()`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
87
+ ```yaml
88
+ applications:
89
+ allowedSpawnCommands:
90
+ - npm
91
+ - node
92
+ ```
100
93
 
101
- 8. **Handle response `headers`**: If you return an object from a REST method with a `headers` property, Harper v5 will use it as the response headers. Ensure any object you return that incidentally has a `headers` property is intentional.
94
+ 7. **Replace `blob.save()`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
102
95
 
103
- 9. **Configure the module loader**: Harper v5 loads application modules through Node.js's VM module API. Control this with the `moduleLoader` setting:
96
+ 8. **Configure the module loader**: Harper v5 loads application modules through Node.js's VM module API. The default mode is `vm-current-context`, which shares JavaScript intrinsics (`Object`, `Array`, `Promise`, etc.) with Harper to avoid `instanceof` and identity-check failures across the application/Harper boundary.
104
97
 
105
- | Value | Behavior |
106
- | -------------------- | ------------------------------------------------ |
107
- | `vm-current-context` | Default. Shares intrinsics with Harper. |
108
- | `vm` | Separate context and intrinsics per application. |
109
- | `native` | Standard `import()`, no application context. |
110
- | `compartment` | SES Compartments; advanced and heavier. |
98
+ ```yaml
99
+ applications:
100
+ lockdown: seal-after-load
101
+ moduleLoader: vm-current-context # vm-current-context (default) | vm | native | compartment
102
+ dependencyLoader: auto # auto (default) | app | native
103
+ allowedDirectory: app # app (default) | any
104
+ ```
111
105
 
112
- The default (`vm-current-context`) avoids `instanceof` failures for values crossing the application/Harper boundary. Choose `vm` only if you need separate per-application intrinsics. Use `native` if the VM loader causes compatibility problems you cannot otherwise resolve.
106
+ - Use `vm` only if you need separate per-application intrinsics.
107
+ - Use `native` to restore pre-v5 behavior (standard `import()`), but note that application-specific context (tagged `logger`, per-app `config`) will not be available.
108
+ - Use `dependencyLoader: native` to apply native loading only to npm packages while keeping the VM loader for first-party source files.
113
109
 
114
- To disable the VM loader entirely and restore pre-v5 behavior:
110
+ 9. **Configure `lockdown`**: The default `lockdown: seal-after-load` seals intrinsic prototypes (`Object`, `Array`, `Promise`, `Map`, `Set`, and others) after all components load, blocking prototype pollution. Before v5.4.0 the default was `freeze-after-load`, which froze the intrinsics instead. If a dependency mutates an intrinsic prototype at runtime and throws a `TypeError`, set `lockdown: none` as a temporary workaround.
115
111
 
116
112
  ```yaml
117
113
  applications:
118
- moduleLoader: native
114
+ lockdown: seal-after-load
119
115
  ```
120
116
 
121
- Note: `logger` and per-app `config` are not available in `native` mode.
117
+ An in-place upgrade from v4 retains the existing config file, which has no `lockdown` value — Harper will not lock intrinsics until you explicitly add the key.
122
118
 
123
- If the goal is only to fix package compatibility while keeping application context for first-party code, `dependencyLoader: native` is a narrower option — it uses native loading only for npm packages while keeping the VM loader for application source files.
119
+ 10. **Check `allowedDirectory` in production**: In production, `allowedDirectory: app` is the default, restricting module loading to the application's own directory tree. If your application loads modules from outside its directory, set `allowedDirectory: any`. This restriction does not apply in dev mode.
124
120
 
125
- 10. **Handle intrinsic `lockdown`**: The default `lockdown` mode (`freeze-after-load`) freezes JavaScript intrinsics (`Object`, `Array`, `Promise`, `Map`, `Set`, etc.) after all application code loads. Any code or dependency that modifies intrinsic prototypes at runtime will throw a `TypeError`. If a dependency requires a temporary workaround, set:
121
+ 11. **Update response objects**: If a REST method returns an object with a `headers` property, Harper v5 will use it as the response headers. Ensure any object with a `headers` property returned from a REST method is intentional.
126
122
 
127
- ```yaml
128
- applications:
129
- lockdown: none
130
- ```
131
-
132
- 11. **Check `allowedDirectory` in production**: In production, applications can only load modules from within their own directory tree (`allowedDirectory: app`). If your application loads files from outside its directory, set:
133
-
134
- ```yaml
135
- applications:
136
- allowedDirectory: any
137
- ```
123
+ 12. **Use `getContext` instead of passing context explicitly**: Context no longer needs to be threaded through every call. Access it via `getContext` exported from `'harper'`. Prefer `static` methods on Resources/Tables for endpoints and access request information from the `target` argument or via `getContext`.
138
124
 
139
125
  ## Examples
140
126
 
@@ -142,7 +128,7 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
142
128
 
143
129
  ```yaml
144
130
  applications:
145
- lockdown: freeze-after-load
131
+ lockdown: seal-after-load
146
132
  moduleLoader: vm-current-context
147
133
  dependencyLoader: auto
148
134
  allowedDirectory: app
@@ -151,15 +137,18 @@ applications:
151
137
  - node
152
138
  ```
153
139
 
154
- ### Updated import and context access
140
+ ### Disabling the VM loader entirely
155
141
 
156
- ```javascript
157
- import { tables, getContext, transaction } from 'harper';
142
+ ```yaml
143
+ applications:
144
+ moduleLoader: native
158
145
  ```
159
146
 
160
- ### Checking `loadedFromSource` after `Table.get`
147
+ ### Checking `loadedFromSource` and using `getContext`
161
148
 
162
149
  ```javascript
150
+ import { getContext, transaction } from 'harper';
151
+
163
152
  const target = new RequestTarget();
164
153
  target.id = id;
165
154
  const record = await Table.get(target);
@@ -168,7 +157,7 @@ if (target.loadedFromSource) {
168
157
  }
169
158
  ```
170
159
 
171
- ### Copying a frozen record before mutation
160
+ ### Spreading a frozen record
172
161
 
173
162
  ```javascript
174
163
  let record = await Table.get(id);
@@ -177,8 +166,8 @@ record = { ...record, property: 'changed' };
177
166
 
178
167
  ## Notes
179
168
 
180
- - The `logger` exported from `'harper'` is tagged with the application name when using the VM module loader. It is not available in `native` mode.
181
- - `instanceof` checks for values crossing the application/Harper boundary will fail when using `moduleLoader: vm` (separate intrinsics). Use `vm-current-context` (the default) to avoid this.
182
- - `import()` behavior depends on the `moduleLoader` setting. In `native` mode, standard Node.js `import()` is used with no application context.
183
- - Automatic context tracking simplifies code but requires explicit `commit()` or new `transaction()` calls when you need to observe data written within the same transaction.
184
- - Use `getContext` from `'harper'` rather than passing context manually through every call — this is the recommended pattern in v5.
169
+ - The `logger` exported from `'harper'` is tagged with the application name when using the VM module loader. It is not available with `moduleLoader: native`.
170
+ - `instanceof` checks for values crossing the application/Harper boundary will fail when using `moduleLoader: vm` (separate intrinsics). Use `moduleLoader: vm-current-context` (the default) to avoid this.
171
+ - `import()` behavior depends on the selected `moduleLoader`. With `native`, it behaves as standard Node.js `import()` with no application context.
172
+ - The `exec` function from `node:child_process` is not usable through the substituted module in v5; `execSync` always throws.
173
+ - Record objects returned by `Table.get` expose `getUpdatedTime` and `getExpiresAt` even though they are frozen plain objects.