@orkestrel/scaffold 0.0.120 → 0.0.121

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 (40) hide show
  1. package/dist/bin/main.js +5 -5
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/claude/agents/orkestrel.md +26 -26
  4. package/dist/host/guides/agent.md +5 -5
  5. package/dist/host/guides/brief.md +7 -15
  6. package/dist/host/guides/browser.md +1 -1
  7. package/dist/host/guides/capture.md +2 -2
  8. package/dist/host/guides/console.md +4 -30
  9. package/dist/host/guides/guide.md +0 -1
  10. package/dist/host/guides/interpret.md +165 -182
  11. package/dist/host/guides/lsp.md +26 -51
  12. package/dist/host/guides/mcp.md +220 -276
  13. package/dist/host/guides/middleware.md +14 -22
  14. package/dist/host/guides/ollama.md +1 -3
  15. package/dist/host/guides/probe.md +71 -80
  16. package/dist/host/guides/program.md +26 -35
  17. package/dist/host/guides/qualifier.md +0 -6
  18. package/dist/host/guides/queue.md +0 -4
  19. package/dist/host/guides/rater.md +6 -12
  20. package/dist/host/guides/relation.md +0 -2
  21. package/dist/host/guides/scaffold.md +12 -8
  22. package/dist/host/guides/sea.md +47 -51
  23. package/dist/host/guides/server.md +15 -19
  24. package/dist/host/guides/terminal.md +0 -26
  25. package/dist/host/guides/toolbox.md +0 -10
  26. package/dist/host/guides/worker.md +57 -57
  27. package/dist/host/guides/workflow.md +13 -26
  28. package/dist/host/guides/workspace.md +15 -21
  29. package/dist/host/manifest.json +28 -448
  30. package/dist/src/core/index.cjs +7 -45
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.js +7 -45
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +10 -9
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +12 -8
  37. package/dist/src/server/index.d.ts +12 -8
  38. package/dist/src/server/index.js +10 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +5 -5
@@ -123,8 +123,6 @@ manager.destroy()
123
123
 
124
124
  ### Types
125
125
 
126
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
127
-
128
126
  | Name | Kind | Signature | Summary |
129
127
  | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
130
128
  | `Decision` | type | `'approved' \| 'denied' \| 'submitted'` | Identifies a final authority outcome, derived from global eligibility. |
@@ -143,7 +141,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
143
141
  | `ProgramDefinition` | interface | `{ id, name, description?, qualification, rating?, notices?, authority?, aggregate?, metadata? }` | Describes a pure authored program definition. |
144
142
  | `ProgramResult` | interface | `{ id, name, eligibility, status, decision?, qualification, rating?, determinations, success, trace, errors }` | Describes one subject's complete program outcome. |
145
143
  | `AggregateResult` | interface | `{ id, name, subjects, determinations, groups, tallies, count, sums, success, trace, errors }` | Describes a batch program outcome across every subject. |
146
- | `ProgramValidationResult` | interface | `{ valid, errors, warnings }` | Describes semantic definition validation. |
147
144
  | `ProgramEventMap` | type | `{ readonly qualify: readonly [result: QualificationResult]; readonly rate: readonly [result: RatingResult]; readonly determine: readonly [result: Determination]; readonly decide: readonly [decision: Decision, result: ProgramResult]; readonly execute: readonly [result: ProgramResult]; readonly aggregate: readonly [result: AggregateResult]; readonly destroy: readonly []; }` | Describes the push observation surface of a `ProgramInterface`. |
148
145
  | `ProgramOptions` | interface | `{ qualifier?, rater?, engine?, validate?, labels?, on?, error? }` | Describes the options for `createProgram` / the `Program` constructor. |
149
146
  | `ProgramInterface` | interface | `{ id, name, definition, emitter, execute(), validate(), destroy() }` | Defines one compiled program that composes one qualifier and one rater over a shared reason engine. |
@@ -155,13 +152,12 @@ Every public data member is `readonly`, every optional key is omitted rather tha
155
152
  `undefined`, and each name is single-word within its entity. Qualifier
156
153
  supplies `Eligibility`, `Premise`, `QualificationDefinition`, and `QualificationResult`;
157
154
  rater supplies `RatingDefinition` and `RatingResult`; reason supplies
158
- `LogicalDefinition`, `Subject`, and the engine; contract supplies `FieldPath` and
155
+ `LogicalDefinition`, `Subject`, the engine, and the `ReasonValidationResult` type
156
+ `validate` returns; contract supplies `FieldPath` and
159
157
  `JSONValue`; the emitter supplies the observation types.
160
158
 
161
159
  ### Constants
162
160
 
163
- A `Shape` cell holds the constant's declared type.
164
-
165
161
  | Name | Kind | Signature | Summary |
166
162
  | -------------------------- | ----- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
167
163
  | `DEFAULT_PROGRAM_VALIDATE` | const | `true` | Names the default definition validation policy, `true`, for `createProgram` / `ProgramManager.add`. |
@@ -213,27 +209,24 @@ except the string-dictionary leaves (`sums`, `scopes`), which certify own member
213
209
  only — a value carrying them on a prototype is admitted unchecked.
214
210
  Holding `isProgramResult` therefore also holds qualifier's published
215
211
  `isQualificationResult` closure and rater's published `isRatingResult` closure.
216
- `isProgramValidationResult` checks this package's own interface directly rather
217
- than delegating to reason's independently evolvable validation contract.
218
-
219
- In a guard table a `Shape` cell holds the type the guard narrows to.
220
-
221
- | Name | Kind | Signature | Summary |
222
- | --------------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
223
- | `isDecision` | const | `Guard<Decision>` | Determines whether a value is a `Decision` literal. |
224
- | `isStatus` | const | `Guard<Status>` | Determines whether a value is a `Status` literal. |
225
- | `isProgramEffect` | const | `Guard<ProgramEffect>` | Determines whether a value is a `ProgramEffect` literal. |
226
- | `isNotice` | function | `(value: unknown) => value is Notice` | Determines whether a value is an exact `Notice` record. |
227
- | `isAggregateDefinition` | function | `(value: unknown) => value is AggregateDefinition` | Determines whether a value is an exact `AggregateDefinition` record. |
228
- | `isProgramDefinition` | function | `(value: unknown) => value is ProgramDefinition` | Determines whether a value is an exact `ProgramDefinition` record. |
229
- | `isProgramSums` | function | `(value: unknown) => value is Readonly<Record<string, number>>` | Determines whether a value is an open program sums record. |
230
- | `isDetermination` | const | `Guard<Determination>` | Determines whether a value is an open result-side `Determination`. |
231
- | `isAggregateGroup` | const | `Guard<AggregateGroup>` | Determines whether a value is an open result-side `AggregateGroup`. |
232
- | `isTally` | const | `Guard<Tally>` | Determines whether a value is an open result-side `Tally`. |
233
- | `isTallies` | function | `(value: unknown) => value is Readonly<Record<Status, Tally>>` | Determines whether a value is a total open status-tally record. |
234
- | `isProgramResult` | const | `Guard<ProgramResult>` | Determines whether a value is an open `ProgramResult`. |
235
- | `isAggregateResult` | const | `Guard<AggregateResult>` | Determines whether a value is an open `AggregateResult`. |
236
- | `isProgramValidationResult` | const | `Guard<ProgramValidationResult>` | Determines whether a value is an open `ProgramValidationResult`. |
212
+ A `validate` result belongs to `@orkestrel/reason`, so narrow one with the
213
+ `isReasonValidationResult` guard from that package.
214
+
215
+ | Name | Kind | Signature | Summary |
216
+ | ----------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
217
+ | `isDecision` | const | `Guard<Decision>` | Determines whether a value is a `Decision` literal. |
218
+ | `isStatus` | const | `Guard<Status>` | Determines whether a value is a `Status` literal. |
219
+ | `isProgramEffect` | const | `Guard<ProgramEffect>` | Determines whether a value is a `ProgramEffect` literal. |
220
+ | `isNotice` | function | `(value: unknown) => value is Notice` | Determines whether a value is an exact `Notice` record. |
221
+ | `isAggregateDefinition` | function | `(value: unknown) => value is AggregateDefinition` | Determines whether a value is an exact `AggregateDefinition` record. |
222
+ | `isProgramDefinition` | function | `(value: unknown) => value is ProgramDefinition` | Determines whether a value is an exact `ProgramDefinition` record. |
223
+ | `isProgramSums` | function | `(value: unknown) => value is Readonly<Record<string, number>>` | Determines whether a value is an open program sums record. |
224
+ | `isDetermination` | const | `Guard<Determination>` | Determines whether a value is an open result-side `Determination`. |
225
+ | `isAggregateGroup` | const | `Guard<AggregateGroup>` | Determines whether a value is an open result-side `AggregateGroup`. |
226
+ | `isTally` | const | `Guard<Tally>` | Determines whether a value is an open result-side `Tally`. |
227
+ | `isTallies` | function | `(value: unknown) => value is Readonly<Record<Status, Tally>>` | Determines whether a value is a total open status-tally record. |
228
+ | `isProgramResult` | const | `Guard<ProgramResult>` | Determines whether a value is an open `ProgramResult`. |
229
+ | `isAggregateResult` | const | `Guard<AggregateResult>` | Determines whether a value is an open `AggregateResult`. |
237
230
 
238
231
  `isProgramSums` checks every own string-named member, including non-enumerable
239
232
  members, as a JavaScript `number`; it ignores inherited and symbol-named members.
@@ -249,7 +242,6 @@ import {
249
242
  isNotice,
250
243
  isProgramDefinition,
251
244
  isProgramResult,
252
- isProgramValidationResult,
253
245
  isStatus,
254
246
  } from '@orkestrel/program'
255
247
 
@@ -261,7 +253,6 @@ isProgramDefinition(definition) // true
261
253
  isDetermination({ id: 'audit', effect: 'notice', applied: true, premises: [] }) // true
262
254
  isProgramResult(program.execute(subject)) // true
263
255
  isAggregateResult(program.execute(subjects)) // true
264
- isProgramValidationResult(program.validate()) // true
265
256
  ```
266
257
 
267
258
  `isProgramDefinition` establishes exact shape only. `Program.validate` additionally
@@ -288,10 +279,10 @@ never destroyed — it holds no state to tear down) purely to drive that reuse.
288
279
  | `buildOutcomeProjection` | function | `(result: ProgramResult) => Readonly<Record<string, unknown>>` | Builds the private authority outcome projection from an assembled program result. |
289
280
  | `buildQualificationSubject` | function | `(subject: Subject, aggregate?: AggregateProjection) => Subject` | Adds optional aggregate context to a private subject copy for qualification. |
290
281
  | `findMissingScopes` | function | `(definition: ProgramDefinition) => readonly string[]` | Returns authored scopes (qualification ruling scopes or notice scopes) that name no rating line on the program. |
291
- | `hasReservedKey` | function | `(subject: Readonly<Record<string, unknown>>) => boolean` | Determines whether a caller subject already carries a reserved program key. |
282
+ | `hasProgramKey` | function | `(subject: Readonly<Record<string, unknown>>) => boolean` | Determines whether a caller subject already carries a reserved program key. |
292
283
  | `assertProgramSubject` | function | `(subject: unknown) => asserts subject is Subject` | Asserts a value is a valid program `Subject`, narrowing it in place. |
293
284
  | `assertProgramDefinition` | function | `(definition: ProgramDefinition) => void` | Asserts a program definition's always-on construction invariants — missing scope references and duplicate rating-line or notice ids. |
294
- | `validateProgramDefinition` | function | `(definition: ProgramDefinition, qualifier: QualifierInterface, engine: ReasonInterface) => ProgramValidationResult` | Validates a program definition's shape, references, and nested definitions. |
285
+ | `validateProgramDefinition` | function | `(definition: ProgramDefinition, qualifier: QualifierInterface, engine: ReasonInterface) => ReasonValidationResult` | Validates a program definition's shape, references, and nested definitions. |
295
286
  | `formatGroupKey` | function | `(subject: Subject, partition: FieldPath) => string` | Coerces a subject's partition-key field to its group-key string. |
296
287
  | `sumFields` | function | `(sums: Readonly<Record<string, number>>, subject: Subject, fields: readonly FieldPath[]) => Readonly<Record<string, number>>` | Folds one subject's finite aggregate field values into a sums record. |
297
288
  | `aggregateSums` | function | `(subjects: readonly Subject[], fields: readonly FieldPath[]) => Readonly<Record<string, number>>` | Sums aggregate fields across a batch of subjects. |
@@ -315,12 +306,12 @@ import {
315
306
  assertProgramDefinition,
316
307
  assertProgramSubject,
317
308
  decideEligibility,
318
- hasReservedKey,
309
+ hasProgramKey,
319
310
  selectProgramLines,
320
311
  } from '@orkestrel/program'
321
312
 
322
- hasReservedKey({ id: 'r1' }) // false
323
- hasReservedKey({ id: 'r1', aggregate: {} }) // true
313
+ hasProgramKey({ id: 'r1' }) // false
314
+ hasProgramKey({ id: 'r1', aggregate: {} }) // true
324
315
  assertProgramSubject({ id: 'r1' }) // narrows to Subject; throws ProgramError('RESERVED') on a reserved key
325
316
  assertProgramDefinition(definition) // throws ProgramError('MISSING' | 'DUPLICATE') at construction, regardless of options.validate
326
317
  selectProgramLines(lines, { wind: 'ineligible' }) // every line except the 'wind' line
@@ -415,7 +406,7 @@ than qualification or rating alone.
415
406
  | Method | Returns | Summary |
416
407
  | ---------- | ------------------------------------ | ---------------------------------------------------------------- |
417
408
  | `execute` | `AggregateResult` or `ProgramResult` | Executes a subject list as one aggregate-aware batch. |
418
- | `validate` | `ProgramValidationResult` | Validates this program's definition and every nested definition. |
409
+ | `validate` | `ReasonValidationResult` | Validates this program's definition and every nested definition. |
419
410
  | `destroy` | `void` | Destroys this program, idempotently. |
420
411
 
421
412
  ```ts
@@ -62,8 +62,6 @@ per subject.
62
62
 
63
63
  ### Types
64
64
 
65
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
66
-
67
65
  | Name | Kind | Signature | Summary |
68
66
  | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
69
67
  | `Eligibility` | type | `'eligible' \| 'ineligible' \| 'referral'` | Represents the eligibility outcome axis. |
@@ -94,8 +92,6 @@ types.
94
92
 
95
93
  ### Constants
96
94
 
97
- A `Shape` cell holds the constant's declared type.
98
-
99
95
  | Name | Kind | Signature | Summary |
100
96
  | ---------------------------- | ----- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
101
97
  | `DEFAULT_QUALIFIER_VALIDATE` | const | `true` | Holds the default definition validation policy for `createQualifier` and `Qualifier.qualify`, `true`. |
@@ -151,8 +147,6 @@ arrays where a record is required, returns `false` for hostile reads, and never
151
147
  result belongs to `@orkestrel/reason`, so narrow one with the `isReasonValidationResult` guard from
152
148
  that package.
153
149
 
154
- In a guard table a `Shape` cell holds the type the guard narrows to.
155
-
156
150
  | Name | Kind | Signature | Summary |
157
151
  | --------------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
158
152
  | `isEligibility` | const | `import("@orkestrel/contract").Guard<"eligible" \| "ineligible" \| "referral">` | Determines whether a value is an `Eligibility` literal. |
@@ -68,8 +68,6 @@ const status = await queue.enqueue('https://example.com')
68
68
 
69
69
  ### Types
70
70
 
71
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
72
-
73
71
  | Name | Kind | Signature | Summary |
74
72
  | --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
73
  | `QueueContext` | interface | `{ id, signal }` | Represents the per-attempt context a queue handler receives. |
@@ -87,8 +85,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
87
85
 
88
86
  ### Guards
89
87
 
90
- In a guard table a `Shape` cell holds the type the guard narrows to.
91
-
92
88
  | Name | Kind | Signature | Summary |
93
89
  | -------------------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
94
90
  | `isQueueError` | function | `(value: unknown) => value is QueueError` | Determines whether an unknown value is a `QueueError`, staying total for a hostile value. |
@@ -64,13 +64,9 @@ is `true` only when every line's `worksheet.success` is `true`.
64
64
 
65
65
  ### Types
66
66
 
67
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
68
- optional member and `plus` introducing its call-signature members, and a type alias's own
69
- type literal with a union's arms escaped as `\|`.
70
-
71
67
  | Name | Kind | Signature | Summary |
72
68
  | ------------------ | --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
73
- | `Stage` | type | `'factor' \| 'group' \| 'total'` | Names a worksheet derivation step stage. |
69
+ | `WorksheetStage` | type | `'factor' \| 'group' \| 'total'` | Names a worksheet derivation step stage. |
74
70
  | `RaterErrorCode` | type | `'DEFINITION' \| 'MISMATCH' \| 'DESTROYED'` | Names a coded `RaterError` programmer-error code. |
75
71
  | `TotalHandler` | type | `(lines: readonly LineResult[]) => number \| undefined` | Represents a pure total port over resolved lines. |
76
72
  | `LineDefinition` | interface | `{ id, name, description?, rate, metadata? }` | Represents one rateable line — a quantitative definition joined to display metadata. |
@@ -87,7 +83,7 @@ type literal with a union's arms escaped as `\|`.
87
83
  | `RaterInterface` | interface | `{ emitter, rate(), destroy() }` | Represents the rating orchestrator over the shared quantitative reasoning engine. |
88
84
 
89
85
  `RaterInterface`'s `emitter` is a `readonly` data member and stays in this table's
90
- `Shape` cell; the interface's call-signature members are documented under
86
+ `Signature` cell; the interface's call-signature members are documented under
91
87
  [Methods](#methods).
92
88
 
93
89
  ### Errors
@@ -129,11 +125,9 @@ or extra members. `isRatingResult` is the borrowed-engine boundary: it and its n
129
125
  result guards reject arrays and check every published typed member without narrowing
130
126
  plain numbers, strings, or unknown values.
131
127
 
132
- In a guard table a `Shape` cell holds the type the guard narrows to.
133
-
134
128
  | Name | Kind | Signature | Summary |
135
129
  | -------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
136
- | `isStage` | const | `Guard<Stage>` | Determines whether a value is a `Stage` literal. |
130
+ | `isWorksheetStage` | const | `Guard<WorksheetStage>` | Determines whether a value is a `WorksheetStage` literal. |
137
131
  | `isLineDefinition` | function | `(value: unknown) => value is LineDefinition` | Determines whether a value is an exact `LineDefinition` record. |
138
132
  | `isRatingDefinition` | function | `(value: unknown) => value is RatingDefinition` | Determines whether a value is an exact `RatingDefinition` record. |
139
133
  | `isEvidence` | function | `(value: unknown) => value is Evidence` | Determines whether a value is an open result-side `Evidence` object. |
@@ -147,10 +141,10 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
147
141
  Each guard answers `true` for a value of its own shape:
148
142
 
149
143
  ```ts
150
- import { isLineDefinition, isRatingDefinition, isStage } from '@orkestrel/rater'
144
+ import { isLineDefinition, isRatingDefinition, isWorksheetStage } from '@orkestrel/rater'
151
145
  import { createQuantitativeDefinition } from '@orkestrel/reason'
152
146
 
153
- isStage('group') // true
147
+ isWorksheetStage('group') // true
154
148
  isLineDefinition({
155
149
  id: 'base',
156
150
  name: 'Base Amount',
@@ -172,7 +166,7 @@ and the worksheet-joining behind `Rater`'s `rate` projection.
172
166
  | `buildEvidenceRows` | function | `(checks: readonly Check[] \| undefined, results: readonly CheckResult[] \| undefined, labels?: Readonly<Record<string, string>>) => readonly Evidence[]` | Builds one evidence row per authored check of a quantitative factor, joined to that check's evaluated result. |
173
167
  | `buildWorksheetFactor` | function | `(definition: Factor, results: readonly FactorResult[], labels?: Readonly<Record<string, string>>) => WorksheetFactor` | Joins one authored quantitative factor to its evaluated `FactorResult`. |
174
168
  | `buildWorksheetGroup` | function | `(definition: QuantitativeDefinition['groups'][number], results: readonly GroupResult[], labels?: Readonly<Record<string, string>>) => WorksheetGroup` | Joins one authored quantitative group to its evaluated `GroupResult`. |
175
- | `buildWorksheetStep` | function | `(stage: Stage, id: string \| undefined, name: string \| undefined, value: number, expression: string) => Step` | Builds one display-neutral `Step` row. |
169
+ | `buildWorksheetStep` | function | `(stage: WorksheetStage, id: string \| undefined, name: string \| undefined, value: number, expression: string) => Step` | Builds one display-neutral `Step` row. |
176
170
  | `buildWorksheetSteps` | function | `(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]) => readonly Step[]` | Builds the ordered `Step` rows for a resolved `Worksheet`. |
177
171
  | `buildWorksheet` | function | `(definition: QuantitativeDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>) => Worksheet` | Joins a `QuantitativeDefinition` and its `QuantitativeResult` into a `Worksheet` — the rating audit trail. |
178
172
  | `buildLineResult` | function | `(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>) => LineResult` | Builds a rated `LineResult` from a line's evaluated `QuantitativeResult`. |
@@ -83,8 +83,6 @@ The error guard recognizes the error's own identity brand across package copies
83
83
  module formats. It accepts subclasses regardless of their `name` and refuses
84
84
  transparent proxies, unbranded look-alikes, and plain branded objects.
85
85
 
86
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
87
-
88
86
  | Name | Kind | Signature | Summary |
89
87
  | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
90
88
  | `Relationship` | type | `'belongs' \| 'many' \| 'one' \| 'through' \| 'morph'` | Enumerates the relationships a relation can declare. |
@@ -398,7 +398,7 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
398
398
  | `HostInventory` | interface | `{ lookup, digests, duplicates, note, surface, unreachable? }` | Represents the committed vendored-file inventory as one call's reads are decided against. |
399
399
  | `HostManifest` | interface | `{ entries, roots, surface, digest }` | Represents the complete vendored-host inventory. |
400
400
  | `HostManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
401
- | `HostStageOptions` | interface | `{ inventory?, establish?, report? }` | Configures the committed inventory baseline and staging reports. |
401
+ | `HostStageOptions` | interface | `{ inventory?, establish?, report?, transfers? }` | Configures the committed inventory baseline and staging reports. |
402
402
  | `MaterializeResult` | interface | `{ target, written, skipped, removed }` | Reports the outcome of one mutation of a target. |
403
403
  | `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
404
404
  | `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
@@ -784,10 +784,11 @@ scaffold surface ../router ../server --from . --json
784
784
  The comparison uses the bare identifier, case included, across declaration keywords and
785
785
  environments. A name claimed by distinct owners is a collision. A collision absent from the record,
786
786
  or carrying an owner absent from its recorded owner set, has `error` standing. When another guide
787
- claims the name, the keeper a `SURFACE_TRANSFERS` entry declares is a recorded owner of it from the
788
- first build after the declaration, so its claim reads `recorded` before its guide is mirrored. A collision with the
789
- same or fewer owners has `recorded` standing. A recorded name that no longer collides has `closed`
790
- standing, so a release can shrink the record.
787
+ claims the name, the keeper a declared transfer names is a recorded owner of it from the first build
788
+ after the declaration, so its claim reads `recorded` before its guide is mirrored. A release build
789
+ declares the transfers in `SURFACE_TRANSFERS`. A collision with the same or fewer owners has
790
+ `recorded` standing. A recorded name that no longer collides has `closed` standing, so a release can
791
+ shrink the record.
791
792
 
792
793
  A name a candidate adds is one its claims hold and its owner's published guide does not. The
793
794
  published guide is read in the order the Claims row gives for any other owner: the guide on `main`,
@@ -2282,6 +2283,7 @@ The inventory contracts carry these data members.
2282
2283
  | `HostStageOptions.inventory` | Optional checkout-relative inventory path. Default: `HOST_INVENTORY_PATH` (`host.json`). |
2283
2284
  | `HostStageOptions.establish` | Optional boolean. If `true`, an absent inventory establishes the baseline; if `false`, staging refuses it. Default: `false`. |
2284
2285
  | `HostStageOptions.report` | Optional callback receiving the baseline location or its absence. Default: no reporting. |
2286
+ | `HostStageOptions.transfers` | Optional readonly `SurfaceTransfer[]` the stage admits. Default: `SURFACE_TRANSFERS`. |
2285
2287
 
2286
2288
  The vendored data root is the shared file set, staged into the published package as plain data.
2287
2289
  Staging walks `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS`, and a release ships what those
@@ -2459,7 +2461,8 @@ committed inventory does not already record: `stageHost` reads the baseline thro
2459
2461
  `readSurfaceBaseline` before the build rewrites the inventory, and refuses a name whose staged
2460
2462
  owner set differs from the inventory — absent from the record, or not a subset of its recorded
2461
2463
  owners — which is what stops a release from widening the set of names more than one package claims.
2462
- A `SURFACE_TRANSFERS` entry that another staged guide claims admits exactly its keeper beside the
2464
+ `HostStageOptions.transfers` declares the transfers, and its default is `SURFACE_TRANSFERS`. A
2465
+ declared transfer that another staged guide claims admits exactly its keeper beside the
2463
2466
  recorded owners, or beside the one owner of a name the record lacks, and the stage records that
2464
2467
  keeper whether or not its guide is mirrored; any other added owner is still refused. A transfer
2465
2468
  whose keeper alone claims the name is spent, and the stage refuses it with `TARGET`, naming the
@@ -2474,8 +2477,9 @@ An absent inventory refuses staging unless `HostStageOptions.establish` is `true
2474
2477
  option to bootstrap a fresh checkout deliberately. An inventory whose `surface` is missing,
2475
2478
  malformed, or at odds with its digest is refused even during bootstrap.
2476
2479
 
2477
- `npm run build` is the release path, and it passes neither `HostStageOptions.inventory` nor
2478
- `HostStageOptions.establish`. Its `build:host` step stages
2480
+ `npm run build` is the release path, and it passes none of `HostStageOptions.inventory`,
2481
+ `HostStageOptions.establish`, and `HostStageOptions.transfers`, so it admits the transfers in
2482
+ `SURFACE_TRANSFERS`. Its `build:host` step stages
2479
2483
  `dist/host`, and its `build:inventory` step stages a temporary root and writes the manifest that
2480
2484
  run produced to `host.json`; each reads the committed inventory at the default path, refuses an
2481
2485
  absent one, and compares the staged collisions against what that inventory records. Deleting
@@ -68,8 +68,6 @@ On Windows, `SEAOptions.windows.sign` is optional Authenticode signing. When pre
68
68
 
69
69
  ### Constants
70
70
 
71
- A `Shape` cell holds the constant's declared type.
72
-
73
71
  | Name | Kind | Signature | Summary |
74
72
  | --------------------------------- | ----- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
75
73
  | `SEA_SENTINEL_FUSE` | const | `"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2"` | Holds the SEA sentinel fuse value embedded in the Node.js binary, `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`. |
@@ -108,55 +106,53 @@ A `Shape` cell holds the constant's declared type.
108
106
 
109
107
  ### Helpers and errors
110
108
 
111
- | Name | Kind | Signature | Summary |
112
- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
113
- | `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
114
- | `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
115
- | `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
116
- | `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
117
- | `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
118
- | `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
119
- | `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
120
- | `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
121
- | `computeSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
122
- | `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
123
- | `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
124
- | `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
125
- | `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
126
- | `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
127
- | `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
128
- | `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
129
- | `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
130
- | `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
131
- | `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
132
- | `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
133
- | `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
134
- | `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
135
- | `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
136
- | `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
137
- | `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
138
- | `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
139
- | `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
140
- | `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
141
- | `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
142
- | `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
143
- | `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
144
- | `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
145
- | `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
146
- | `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
147
- | `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
148
- | `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
149
- | `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
150
- | `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
151
- | `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
152
- | `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
153
- | `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
154
- | `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
109
+ | Name | Kind | Signature | Summary |
110
+ | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
111
+ | `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
112
+ | `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
113
+ | `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
114
+ | `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
115
+ | `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
116
+ | `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
117
+ | `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
118
+ | `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
119
+ | `computeCompressionSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
120
+ | `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
121
+ | `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
122
+ | `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
123
+ | `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
124
+ | `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
125
+ | `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
126
+ | `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
127
+ | `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
128
+ | `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
129
+ | `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
130
+ | `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
131
+ | `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
132
+ | `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
133
+ | `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
134
+ | `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
135
+ | `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
136
+ | `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
137
+ | `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
138
+ | `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
139
+ | `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
140
+ | `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
141
+ | `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
142
+ | `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
143
+ | `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
144
+ | `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
145
+ | `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
146
+ | `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
147
+ | `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
148
+ | `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
149
+ | `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
150
+ | `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
151
+ | `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
152
+ | `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
155
153
 
156
154
  ### Types
157
155
 
158
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
159
-
160
156
  | Name | Kind | Signature | Summary |
161
157
  | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
162
158
  | `SEACompressionSize` | interface | `{ original, compressed, ratio }` | Represents a size comparison between original and compressed data. |
@@ -197,7 +193,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
197
193
 
198
194
  ## Methods
199
195
 
200
- The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `Shape` cell and off these tables: `format` on `InjectorInterface`, `emitter` and `status` on `SEAInterface`, `emitter` and `count` on `AssetManagerInterface`. Each concrete class implements its interface exactly, so this doubles as the class's instance-method surface.
196
+ The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `Signature` cell and off these tables: `format` on `InjectorInterface`, `emitter` and `status` on `SEAInterface`, `emitter` and `count` on `AssetManagerInterface`. Each concrete class implements its interface exactly, so this doubles as the class's instance-method surface.
201
197
 
202
198
  #### `SEAInterface`
203
199
 
@@ -289,7 +285,7 @@ import {
289
285
  ensureExists,
290
286
  isCompressible,
291
287
  walkDirectory,
292
- computeSize,
288
+ computeCompressionSize,
293
289
  compressFile,
294
290
  compressDirectory,
295
291
  formatSize,
@@ -333,7 +329,7 @@ ensureExists('dist/server/serve.cjs', 'entry file is missing')
333
329
  walkDirectory('dist/app/browser') // every relative file path under the directory
334
330
  isCompressible('dist/app/browser/index.html') // true — not in SKIP_EXTENSIONS
335
331
 
336
- const size = computeSize(1000, 400) // { original: 1000, compressed: 400, ratio: 0.4 }
332
+ const size = computeCompressionSize(1000, 400) // { original: 1000, compressed: 400, ratio: 0.4 }
337
333
  compressFile('dist/index.html', 'dist/index.html.br')
338
334
  compressDirectory('dist/app/browser', { mode: 'text' })
339
335