@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.
- package/dist/bin/main.js +5 -5
- package/dist/bin/main.js.map +1 -1
- package/dist/host/claude/agents/orkestrel.md +26 -26
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/scaffold.md +12 -8
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +28 -448
- package/dist/src/core/index.cjs +7 -45
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +7 -45
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +10 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -8
- package/dist/src/server/index.d.ts +12 -8
- package/dist/src/server/index.js +10 -9
- package/dist/src/server/index.js.map +1 -1
- 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`,
|
|
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
|
-
`
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
|
222
|
-
|
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
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
|
-
| `
|
|
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) =>
|
|
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
|
-
|
|
309
|
+
hasProgramKey,
|
|
319
310
|
selectProgramLines,
|
|
320
311
|
} from '@orkestrel/program'
|
|
321
312
|
|
|
322
|
-
|
|
323
|
-
|
|
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` | `
|
|
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
|
-
| `
|
|
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
|
-
`
|
|
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
|
-
| `
|
|
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,
|
|
144
|
+
import { isLineDefinition, isRatingDefinition, isWorksheetStage } from '@orkestrel/rater'
|
|
151
145
|
import { createQuantitativeDefinition } from '@orkestrel/reason'
|
|
152
146
|
|
|
153
|
-
|
|
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:
|
|
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? }`
|
|
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
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
standing, so a release can
|
|
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
|
-
|
|
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
|
|
2478
|
-
`HostStageOptions.establish
|
|
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
|
package/dist/host/guides/sea.md
CHANGED
|
@@ -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
|
|
112
|
-
|
|
|
113
|
-
| `isExecutableFormat`
|
|
114
|
-
| `resolvePlatform`
|
|
115
|
-
| `isPlatformSupported`
|
|
116
|
-
| `ensureExists`
|
|
117
|
-
| `isCompressible`
|
|
118
|
-
| `walkDirectory`
|
|
119
|
-
| `executeShell`
|
|
120
|
-
| `redactCommand`
|
|
121
|
-
| `
|
|
122
|
-
| `compressFile`
|
|
123
|
-
| `compressDirectory`
|
|
124
|
-
| `alignTo`
|
|
125
|
-
| `readPEOffset`
|
|
126
|
-
| `readU16`
|
|
127
|
-
| `readU32`
|
|
128
|
-
| `readU64`
|
|
129
|
-
| `writeU16`
|
|
130
|
-
| `writeU32`
|
|
131
|
-
| `writeU64`
|
|
132
|
-
| `appendFile`
|
|
133
|
-
| `stripTrailingNulls`
|
|
134
|
-
| `isPEExecutable`
|
|
135
|
-
| `patchPESubsystem`
|
|
136
|
-
| `stripPESignature`
|
|
137
|
-
| `buildSignCommand`
|
|
138
|
-
| `formatSize`
|
|
139
|
-
| `ensureSafeKey`
|
|
140
|
-
| `ensureContained`
|
|
141
|
-
| `ensureSafeName`
|
|
142
|
-
| `finalizeExecutable`
|
|
143
|
-
| `syncDirectory`
|
|
144
|
-
| `buildBlobConfig`
|
|
145
|
-
| `patchSentinelFuse`
|
|
146
|
-
| `buildELFNoteHeader`
|
|
147
|
-
| `alignELFNoteSize`
|
|
148
|
-
| `isPowerOfTwo`
|
|
149
|
-
| `copyRange`
|
|
150
|
-
| `openBrowser`
|
|
151
|
-
| `SEAError`
|
|
152
|
-
| `isSEAError`
|
|
153
|
-
| `ShellError`
|
|
154
|
-
| `isShellError`
|
|
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 `
|
|
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
|
-
|
|
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 =
|
|
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
|
|