@orkestrel/scaffold 0.0.119 → 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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -70,6 +70,16 @@ export declare function applyOverrides(artifacts: readonly Artifact[], overrides
70
70
  */
71
71
  export declare type Artifact = HostArtifact | HydratedArtifact | ContentArtifact;
72
72
 
73
+ /**
74
+ * Lists the `ArtifactGroup` values in plan order, frozen.
75
+ *
76
+ * @remarks
77
+ * A compile that names no groups covers every one of them, so this list is the
78
+ * default selection as well as the accepted candidates for a rejected one. The
79
+ * order is the order a plan lists its artifacts in.
80
+ */
81
+ export declare const ARTIFACT_GROUPS: readonly ArtifactGroup[];
82
+
73
83
  /**
74
84
  * Holds formatter-stable template text for source, test, document, guide, and service artifacts.
75
85
  *
@@ -95,11 +105,79 @@ export declare const ARTIFACT_TEMPLATES: ArtifactTemplateSet;
95
105
  /** Describes the fields every planned file carries. */
96
106
  export declare interface ArtifactBase {
97
107
  readonly path: string;
98
- readonly group: Group;
108
+ readonly group: ArtifactGroup;
99
109
  readonly ownership: Ownership;
100
110
  readonly environment?: Environment;
101
111
  }
102
112
 
113
+ /**
114
+ * Names how one target path compares to the artifact planned for it.
115
+ *
116
+ * @remarks
117
+ * `foreign` is a path the plan does not own at all. It is also the set
118
+ * `overwrite` deletes from, narrowed by the paths no verb may remove and by
119
+ * what git tracks.
120
+ */
121
+ export declare type ArtifactDrift = 'aligned' | 'stale' | 'missing' | 'foreign';
122
+
123
+ /**
124
+ * Represents one drift verdict against a target path.
125
+ *
126
+ * @remarks
127
+ * `observed` carries the destination's exact bytes and is the precondition the
128
+ * mutation is held to: a write that replaces stale bytes and a deletion that
129
+ * removes a foreign file each fail when the destination no longer matches what
130
+ * the finding recorded. Both therefore require it, and the requirement is in
131
+ * the type rather than in prose, because a deletion that cannot bind to what
132
+ * the audit showed is the one thing the destructive verb must never do. A
133
+ * missing destination has no bytes to record. An aligned one may have gone
134
+ * uncompared, which is what a birth-owned path always does, so it records
135
+ * bytes only where they were actually read. Every planned finding carries its
136
+ * artifact's {@link Ownership}, so a consumer reads what scaffold claims at the
137
+ * path from the finding itself. A foreign finding has no planned artifact and
138
+ * therefore no ownership.
139
+ *
140
+ * Which combinations of `ownership`, `drift`, and `observed` a real audit
141
+ * produces is {@link inferArtifactDrift}'s law, not this type's. A birth-owned path is
142
+ * never compared and is always aligned, a presence-owned path compares existence
143
+ * only, and bytes are recorded only where they were read. This shape therefore
144
+ * admits a combination that law never produces — a birth-owned path reported
145
+ * stale is the plainest one — and it admits it deliberately: restating the
146
+ * comparison's case analysis here would be a second copy of it, able to disagree
147
+ * with the one that decides. What closes the gap is the writer: `repair` and
148
+ * `remove` re-derive every verdict themselves and refuse a caller's audit that
149
+ * does not match, so a verdict the comparison could not have reached is refused
150
+ * rather than acted on.
151
+ */
152
+ export declare type ArtifactFinding = {
153
+ readonly path: string;
154
+ readonly group: ArtifactGroup;
155
+ readonly ownership: Ownership;
156
+ readonly drift: 'stale';
157
+ readonly observed: string;
158
+ } | {
159
+ readonly path: string;
160
+ readonly group: ArtifactGroup;
161
+ readonly ownership?: never;
162
+ readonly drift: 'foreign';
163
+ readonly observed: string;
164
+ } | {
165
+ readonly path: string;
166
+ readonly group: ArtifactGroup;
167
+ readonly ownership: Ownership;
168
+ readonly drift: 'missing';
169
+ readonly observed?: never;
170
+ } | {
171
+ readonly path: string;
172
+ readonly group: ArtifactGroup;
173
+ readonly ownership: Ownership;
174
+ readonly drift: 'aligned';
175
+ readonly observed?: string;
176
+ };
177
+
178
+ /** Names the artifact group a plan selects over. */
179
+ export declare type ArtifactGroup = 'manifest' | 'configs' | 'source' | 'tests' | 'guides' | 'docs' | 'orchestration';
180
+
103
181
  /**
104
182
  * Measures a drafted artifact list against the laws a whole plan decides.
105
183
  *
@@ -206,7 +284,7 @@ export declare interface ArtifactTemplateSet {
206
284
  * exactly where bytes were read.
207
285
  *
208
286
  * @remarks
209
- * The comparison itself is {@link inferDrift}'s, so ownership decides it here
287
+ * The comparison itself is {@link inferArtifactDrift}'s, so ownership decides it here
210
288
  * exactly as it does everywhere else. This adds only the shape: a missing
211
289
  * destination has no bytes to record, and every other verdict records the bytes
212
290
  * it was given, which is the precondition the mutation that follows is held to.
@@ -218,15 +296,15 @@ export declare interface ArtifactTemplateSet {
218
296
  *
219
297
  * @example
220
298
  * ```ts
221
- * import { artifactToFinding } from '@orkestrel/scaffold'
299
+ * import { artifactToArtifactFinding } from '@orkestrel/scaffold'
222
300
  *
223
- * artifactToFinding(
301
+ * artifactToArtifactFinding(
224
302
  * { path: 'README.md', group: 'docs', ownership: 'content', origin: 'computed', content: 'hi\n' },
225
303
  * '6279650a',
226
304
  * ) // { path: 'README.md', group: 'docs', ownership: 'content', drift: 'stale', observed: '6279650a' }
227
305
  * ```
228
306
  */
229
- export declare function artifactToFinding(artifact: Artifact, observed?: string): Finding;
307
+ export declare function artifactToArtifactFinding(artifact: Artifact, observed?: string): ArtifactFinding;
230
308
 
231
309
  /**
232
310
  * Projects an artifact to the exact bytes it claims, as hexadecimal.
@@ -265,7 +343,7 @@ export declare function artifactToHex(artifact: Artifact): string | undefined;
265
343
  * separately bounded plan artifacts and snapshot paths.
266
344
  */
267
345
  export declare interface Audit {
268
- readonly findings: readonly Finding[];
346
+ readonly findings: readonly ArtifactFinding[];
269
347
  readonly questions: readonly Question[];
270
348
  }
271
349
 
@@ -522,7 +600,7 @@ export declare function blueprintToGuideArtifacts(blueprint: Blueprint): readonl
522
600
  *
523
601
  * `source` is left absent because it falls back to `path`, and every vendored
524
602
  * path is stored under the name it is written to. The group comes from
525
- * {@link inferGroup}, so a vendored path and a foreign path found in a target
603
+ * {@link inferArtifactGroup}, so a vendored path and a foreign path found in a target
526
604
  * are classified by one rule and a plan never disagrees with the audit beside
527
605
  * it.
528
606
  *
@@ -1201,50 +1279,6 @@ export declare type CatalogEntry = {
1201
1279
  */
1202
1280
  export declare function catalogToLayers(entries: readonly CatalogEntry[]): ReadonlyArray<readonly string[]>;
1203
1281
 
1204
- /**
1205
- * Snapshots an untrusted value into exact JSON data the caller owns.
1206
- *
1207
- * @param value - The untrusted value to take ownership of.
1208
- * @returns A deeply frozen copy sharing nothing with `value`, or `undefined`
1209
- * when the value is not exact acyclic JSON data.
1210
- *
1211
- * @remarks
1212
- * This fixes the order every boundary in this package reads a caller's value
1213
- * in: snapshot first, then guard the snapshot. A guard reads `value[key]`, so a
1214
- * property backed by an accessor can answer one thing while the guard runs and
1215
- * another while the accepted value is used, and no guard closes that race from
1216
- * inside. The snapshot closes it. The installed `cloneJSONValue` refuses any
1217
- * property that is not an own enumerable data property, so an accessor never
1218
- * reaches the guard at all, and it reads every value it keeps exactly once from
1219
- * that property's descriptor. What the guard measures is what every later read
1220
- * returns.
1221
- *
1222
- * The result is a frozen null-prototype record or a frozen intrinsic array, and
1223
- * this package's guards accept both, so the snapshot passes `isBlueprint`,
1224
- * `isSnapshot`, and the parsers derived from them unchanged.
1225
- *
1226
- * Ownership is refused rather than raised. A value carrying a function, an
1227
- * `undefined`, a symbol key, a cycle, a non-finite number, or more nodes than
1228
- * `@orkestrel/contract` admits answers `undefined`, which leaves each caller
1229
- * free to decide what a refusal means — the compiler throws `INVALID`, the gate
1230
- * asks a `Question` — and keeps `ScaffoldError` the only error this package
1231
- * throws.
1232
- *
1233
- * The node ceiling is the installed package's `CLONE_NODE_LIMIT`, and it counts
1234
- * every record, array, and leaf the snapshot would contain, so it bounds breadth
1235
- * and depth together. This package declares no ceiling of its own beside it: a
1236
- * local number no code here can enforce could only disagree with the one that
1237
- * binds.
1238
- *
1239
- * @example
1240
- * ```ts
1241
- * import { cloneValue, parseBlueprint } from '@orkestrel/scaffold'
1242
- *
1243
- * const owned = parseBlueprint(cloneValue(input))
1244
- * ```
1245
- */
1246
- export declare function cloneValue(value: unknown): JSONValue | undefined;
1247
-
1248
1282
  /**
1249
1283
  * Collects the near names and equal contracts other owners claim beside each name a candidate adds.
1250
1284
  *
@@ -1369,7 +1403,7 @@ export declare interface CompileFailure {
1369
1403
  * so a caller reads the refusal from the value it asked for.
1370
1404
  *
1371
1405
  * Both entry points snapshot each caller-supplied value and then guard the
1372
- * snapshot, which is the order `cloneValue` fixes. A value that is not the exact
1406
+ * snapshot, which is the order `parseOwnedJSONValue` fixes. A value that is not the exact
1373
1407
  * shape is off-contract input rather than an answerable question, so it raises
1374
1408
  * `INVALID`. Structure raises; the laws a well-formed blueprint can still break
1375
1409
  * are the gate's, and they answer with questions.
@@ -1445,7 +1479,7 @@ export declare class Compiler implements CompilerInterface {
1445
1479
  * new Compiler().compile(blueprint, ['manifest']).plan?.artifacts.length // 1
1446
1480
  * ```
1447
1481
  */
1448
- compile(blueprint: Blueprint, groups?: readonly Group[]): CompileResult;
1482
+ compile(blueprint: Blueprint, groups?: readonly ArtifactGroup[]): CompileResult;
1449
1483
  /**
1450
1484
  * Compiles a blueprint and compares its plan to a target's current content.
1451
1485
  *
@@ -1476,7 +1510,7 @@ export declare class Compiler implements CompilerInterface {
1476
1510
  * new Compiler().audit(blueprint, {}, ['configs']).findings[0]?.drift // 'missing'
1477
1511
  * ```
1478
1512
  */
1479
- audit(blueprint: Blueprint, current: Snapshot, groups?: readonly Group[]): Audit;
1513
+ audit(blueprint: Blueprint, current: Snapshot, groups?: readonly ArtifactGroup[]): Audit;
1480
1514
  /**
1481
1515
  * Tears the compiler down. Every later call throws, and teardown is idempotent.
1482
1516
  *
@@ -1543,7 +1577,7 @@ export declare class Compiler implements CompilerInterface {
1543
1577
  * @param groups - The artifact groups to cover; every group when absent.
1544
1578
  * @returns The compile result, carrying a plan only when the gate passed.
1545
1579
  */
1546
- compile(blueprint: Blueprint, groups?: readonly Group[]): CompileResult;
1580
+ compile(blueprint: Blueprint, groups?: readonly ArtifactGroup[]): CompileResult;
1547
1581
  /**
1548
1582
  * Compiles a blueprint and compares its plan to a target's current content.
1549
1583
  *
@@ -1552,7 +1586,7 @@ export declare class Compiler implements CompilerInterface {
1552
1586
  * @param groups - The artifact groups to cover; every group when absent.
1553
1587
  * @returns The audit; empty findings and blocking questions when the gate refused.
1554
1588
  */
1555
- audit(blueprint: Blueprint, current: Snapshot, groups?: readonly Group[]): Audit;
1589
+ audit(blueprint: Blueprint, current: Snapshot, groups?: readonly ArtifactGroup[]): Audit;
1556
1590
  /**
1557
1591
  * Tears the compiler down. Every later call throws, and teardown is idempotent.
1558
1592
  *
@@ -1909,16 +1943,6 @@ export declare class Compiler implements CompilerInterface {
1909
1943
  /** Names the generated packed-package proof every publishing workspace is planned at. */
1910
1944
  export declare const DISTRIBUTION_TEST_PATH = "tests/distribution.test.ts";
1911
1945
 
1912
- /**
1913
- * Names how one target path compares to the artifact planned for it.
1914
- *
1915
- * @remarks
1916
- * `foreign` is a path the plan does not own at all. It is also the set
1917
- * `overwrite` deletes from, narrowed by the paths no verb may remove and by
1918
- * what git tracks.
1919
- */
1920
- export declare type Drift = 'aligned' | 'stale' | 'missing' | 'foreign';
1921
-
1922
1946
  /** Matches the minimum-Node engine syntax a blueprint declares. */
1923
1947
  export declare const ENGINES_PATTERN: RegExp;
1924
1948
 
@@ -2002,61 +2026,6 @@ export declare class Compiler implements CompilerInterface {
2002
2026
  */
2003
2027
  export declare function extractVersion(version: string): readonly [major: number, minor: number, patch: number] | undefined;
2004
2028
 
2005
- /**
2006
- * Represents one drift verdict against a target path.
2007
- *
2008
- * @remarks
2009
- * `observed` carries the destination's exact bytes and is the precondition the
2010
- * mutation is held to: a write that replaces stale bytes and a deletion that
2011
- * removes a foreign file each fail when the destination no longer matches what
2012
- * the finding recorded. Both therefore require it, and the requirement is in
2013
- * the type rather than in prose, because a deletion that cannot bind to what
2014
- * the audit showed is the one thing the destructive verb must never do. A
2015
- * missing destination has no bytes to record. An aligned one may have gone
2016
- * uncompared, which is what a birth-owned path always does, so it records
2017
- * bytes only where they were actually read. Every planned finding carries its
2018
- * artifact's {@link Ownership}, so a consumer reads what scaffold claims at the
2019
- * path from the finding itself. A foreign finding has no planned artifact and
2020
- * therefore no ownership.
2021
- *
2022
- * Which combinations of `ownership`, `drift`, and `observed` a real audit
2023
- * produces is {@link inferDrift}'s law, not this type's. A birth-owned path is
2024
- * never compared and is always aligned, a presence-owned path compares existence
2025
- * only, and bytes are recorded only where they were read. This shape therefore
2026
- * admits a combination that law never produces — a birth-owned path reported
2027
- * stale is the plainest one — and it admits it deliberately: restating the
2028
- * comparison's case analysis here would be a second copy of it, able to disagree
2029
- * with the one that decides. What closes the gap is the writer: `repair` and
2030
- * `remove` re-derive every verdict themselves and refuse a caller's audit that
2031
- * does not match, so a verdict the comparison could not have reached is refused
2032
- * rather than acted on.
2033
- */
2034
- export declare type Finding = {
2035
- readonly path: string;
2036
- readonly group: Group;
2037
- readonly ownership: Ownership;
2038
- readonly drift: 'stale';
2039
- readonly observed: string;
2040
- } | {
2041
- readonly path: string;
2042
- readonly group: Group;
2043
- readonly ownership?: never;
2044
- readonly drift: 'foreign';
2045
- readonly observed: string;
2046
- } | {
2047
- readonly path: string;
2048
- readonly group: Group;
2049
- readonly ownership: Ownership;
2050
- readonly drift: 'missing';
2051
- readonly observed?: never;
2052
- } | {
2053
- readonly path: string;
2054
- readonly group: Group;
2055
- readonly ownership: Ownership;
2056
- readonly drift: 'aligned';
2057
- readonly observed?: string;
2058
- };
2059
-
2060
2029
  /**
2061
2030
  * Matches the exact `major.minor.patch` floor accepted for a foreign peer's range.
2062
2031
  *
@@ -2105,19 +2074,6 @@ export declare class Compiler implements CompilerInterface {
2105
2074
  /** Names the shared Vitest global-setup module whose presence makes a workspace `global`. */
2106
2075
  export declare const GLOBAL_SETUP_PATH = "tests/setupGlobal.ts";
2107
2076
 
2108
- /** Names the artifact group a plan selects over. */
2109
- export declare type Group = 'manifest' | 'configs' | 'source' | 'tests' | 'guides' | 'docs' | 'orchestration';
2110
-
2111
- /**
2112
- * Lists the `Group` values in plan order, frozen.
2113
- *
2114
- * @remarks
2115
- * A compile that names no groups covers every one of them, so this list is the
2116
- * default selection as well as the accepted candidates for a rejected one. The
2117
- * order is the order a plan lists its artifacts in.
2118
- */
2119
- export declare const GROUPS: readonly Group[];
2120
-
2121
2077
  /** Names the package-owned guide-parity entry used by `test:guides` and to select the `guides` project. */
2122
2078
  export declare const GUIDES_TEST_PATH = "tests/guides.test.ts";
2123
2079
 
@@ -2185,7 +2141,7 @@ export declare class Compiler implements CompilerInterface {
2185
2141
  * one that produced no answer carries the cause and no bytes. `observed` is the target's
2186
2142
  * file as exact bytes when the read was made, and is absent when the target
2187
2143
  * holds no such file; it is the precondition the write is held to, exactly as
2188
- * {@link Finding.observed} is.
2144
+ * {@link ArtifactFinding.observed} is.
2189
2145
  *
2190
2146
  * A found row may carry the target's own bytes rather than read ones, where
2191
2147
  * those bytes already satisfy the claim the read was going to check. They are
@@ -2244,7 +2200,7 @@ export declare class Compiler implements CompilerInterface {
2244
2200
  * @example
2245
2201
  * ```ts
2246
2202
  * import type { Artifact } from '@orkestrel/scaffold'
2247
- * import { inferDrift } from '@orkestrel/scaffold'
2203
+ * import { inferArtifactDrift } from '@orkestrel/scaffold'
2248
2204
  *
2249
2205
  * const artifact: Artifact = {
2250
2206
  * path: 'README.md',
@@ -2254,15 +2210,15 @@ export declare class Compiler implements CompilerInterface {
2254
2210
  * content: 'hi\n',
2255
2211
  * }
2256
2212
  *
2257
- * inferDrift(artifact, '68690a') // 'aligned'
2258
- * inferDrift(artifact, '6279650a') // 'stale'
2259
- * inferDrift(artifact) // 'missing'
2213
+ * inferArtifactDrift(artifact, '68690a') // 'aligned'
2214
+ * inferArtifactDrift(artifact, '6279650a') // 'stale'
2215
+ * inferArtifactDrift(artifact) // 'missing'
2260
2216
  * ```
2261
2217
  */
2262
- export declare function inferDrift(artifact: Artifact, observed?: string): Exclude<Drift, 'foreign'>;
2218
+ export declare function inferArtifactDrift(artifact: Artifact, observed?: string): Exclude<ArtifactDrift, 'foreign'>;
2263
2219
 
2264
2220
  /**
2265
- * Infers the {@link Group} a path belongs to.
2221
+ * Infers the {@link ArtifactGroup} a path belongs to.
2266
2222
  *
2267
2223
  * @param path - The target-relative path to classify.
2268
2224
  * @returns The group that owns the path.
@@ -2278,14 +2234,14 @@ export declare class Compiler implements CompilerInterface {
2278
2234
  *
2279
2235
  * @example
2280
2236
  * ```ts
2281
- * import { inferGroup } from '@orkestrel/scaffold'
2237
+ * import { inferArtifactGroup } from '@orkestrel/scaffold'
2282
2238
  *
2283
- * inferGroup('src/core/index.ts') // 'source'
2284
- * inferGroup('AGENTS.md') // 'docs'
2285
- * inferGroup('.editorconfig') // 'configs'
2239
+ * inferArtifactGroup('src/core/index.ts') // 'source'
2240
+ * inferArtifactGroup('AGENTS.md') // 'docs'
2241
+ * inferArtifactGroup('.editorconfig') // 'configs'
2286
2242
  * ```
2287
2243
  */
2288
- export declare function inferGroup(path: string): Group;
2244
+ export declare function inferArtifactGroup(path: string): ArtifactGroup;
2289
2245
 
2290
2246
  /**
2291
2247
  * Infers how two different names resemble each other by spelling.
@@ -2396,6 +2352,38 @@ export declare class Compiler implements CompilerInterface {
2396
2352
  */
2397
2353
  export declare const isArtifact: Guard<Artifact>;
2398
2354
 
2355
+ /**
2356
+ * Narrows a value to an {@link ArtifactFinding}.
2357
+ *
2358
+ * @remarks
2359
+ * `observed` is required exactly where the mutation it precedes is held to it,
2360
+ * absent where the destination had no bytes to record, and optional where the
2361
+ * comparison may not have been made. Planned findings require `ownership`;
2362
+ * foreign findings forbid it because no artifact was planned for their path.
2363
+ *
2364
+ * That is the whole claim. This guard proves the shape a reader may destructure
2365
+ * and nothing about whether the verdict is one an audit could have reached: the
2366
+ * correlation between `ownership`, `drift`, and `observed` belongs to
2367
+ * {@link inferArtifactDrift}, and it is re-derived at the verb that acts on the finding.
2368
+ */
2369
+ export declare const isArtifactFinding: Guard<ArtifactFinding>;
2370
+
2371
+ /**
2372
+ * Narrows a value to one {@link ArtifactGroup} a plan selects over.
2373
+ *
2374
+ * @example
2375
+ * ```ts
2376
+ * import { isArtifactGroup } from '@orkestrel/scaffold'
2377
+ *
2378
+ * isArtifactGroup('manifest') // true
2379
+ * isArtifactGroup('readme') // false
2380
+ * ```
2381
+ */
2382
+ export declare const isArtifactGroup: Guard<ArtifactGroup>;
2383
+
2384
+ /** Narrows a value to a bounded group selection. */
2385
+ export declare const isArtifactGroups: Guard<readonly ArtifactGroup[]>;
2386
+
2399
2387
  /**
2400
2388
  * Narrows a value to an {@link Audit}.
2401
2389
  *
@@ -2620,22 +2608,6 @@ export declare class Compiler implements CompilerInterface {
2620
2608
  */
2621
2609
  export declare const isExtension: Guard<Extension>;
2622
2610
 
2623
- /**
2624
- * Narrows a value to a {@link Finding}.
2625
- *
2626
- * @remarks
2627
- * `observed` is required exactly where the mutation it precedes is held to it,
2628
- * absent where the destination had no bytes to record, and optional where the
2629
- * comparison may not have been made. Planned findings require `ownership`;
2630
- * foreign findings forbid it because no artifact was planned for their path.
2631
- *
2632
- * That is the whole claim. This guard proves the shape a reader may destructure
2633
- * and nothing about whether the verdict is one an audit could have reached: the
2634
- * correlation between `ownership`, `drift`, and `observed` belongs to
2635
- * {@link inferDrift}, and it is re-derived at the verb that acts on the finding.
2636
- */
2637
- export declare const isFinding: Guard<Finding>;
2638
-
2639
2611
  /**
2640
2612
  * Checks whether a destination's floor bytes survive a live overlay.
2641
2613
  *
@@ -2661,22 +2633,6 @@ export declare class Compiler implements CompilerInterface {
2661
2633
  */
2662
2634
  export declare function isFloorPath(path: string): boolean;
2663
2635
 
2664
- /**
2665
- * Narrows a value to one {@link Group} a plan selects over.
2666
- *
2667
- * @example
2668
- * ```ts
2669
- * import { isGroup } from '@orkestrel/scaffold'
2670
- *
2671
- * isGroup('manifest') // true
2672
- * isGroup('readme') // false
2673
- * ```
2674
- */
2675
- export declare const isGroup: Guard<Group>;
2676
-
2677
- /** Narrows a value to a bounded group selection. */
2678
- export declare const isGroups: Guard<readonly Group[]>;
2679
-
2680
2636
  /**
2681
2637
  * Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit.
2682
2638
  *
@@ -2687,13 +2643,13 @@ export declare class Compiler implements CompilerInterface {
2687
2643
  *
2688
2644
  * @example
2689
2645
  * ```ts
2690
- * import { isHex } from '@orkestrel/scaffold'
2646
+ * import { isHexContent } from '@orkestrel/scaffold'
2691
2647
  *
2692
- * isHex('68690a') // true
2693
- * isHex('68690A') // false
2648
+ * isHexContent('68690a') // true
2649
+ * isHexContent('68690A') // false
2694
2650
  * ```
2695
2651
  */
2696
- export declare const isHex: Guard<string>;
2652
+ export declare const isHexContent: Guard<string>;
2697
2653
 
2698
2654
  /**
2699
2655
  * Narrows a value to a {@link ManifestScript}.
@@ -3070,12 +3026,12 @@ export declare class Compiler implements CompilerInterface {
3070
3026
  export declare function manifestToName(manifest: string): string | undefined;
3071
3027
 
3072
3028
  /**
3073
- * Tests whether {@link inferDrift} could have produced a finding for an ownership.
3029
+ * Tests whether {@link inferArtifactDrift} could have produced a finding for an ownership.
3074
3030
  *
3075
3031
  * @param ownership - What scaffold claims at the planned path.
3076
3032
  * @param finding - The audit verdict to test.
3077
3033
  * @returns True if the ownership and verdict are reachable through
3078
- * {@link inferDrift}; false otherwise.
3034
+ * {@link inferArtifactDrift}; false otherwise.
3079
3035
  *
3080
3036
  * @remarks
3081
3037
  * This predicate keeps the comparison law beside the reachability law it
@@ -3084,16 +3040,16 @@ export declare class Compiler implements CompilerInterface {
3084
3040
  *
3085
3041
  * @example
3086
3042
  * ```ts
3087
- * import type { Finding } from '@orkestrel/scaffold'
3088
- * import { matchesDriftReachability } from '@orkestrel/scaffold'
3043
+ * import type { ArtifactFinding } from '@orkestrel/scaffold'
3044
+ * import { matchesArtifactDriftReachability } from '@orkestrel/scaffold'
3089
3045
  *
3090
- * const aligned: Finding = {
3046
+ * const aligned: ArtifactFinding = {
3091
3047
  * path: 'README.md',
3092
3048
  * group: 'docs',
3093
3049
  * ownership: 'birth',
3094
3050
  * drift: 'aligned',
3095
3051
  * }
3096
- * const stale: Finding = {
3052
+ * const stale: ArtifactFinding = {
3097
3053
  * path: 'README.md',
3098
3054
  * group: 'docs',
3099
3055
  * ownership: 'birth',
@@ -3101,11 +3057,11 @@ export declare class Compiler implements CompilerInterface {
3101
3057
  * observed: '6279650a',
3102
3058
  * }
3103
3059
  *
3104
- * matchesDriftReachability('birth', aligned) // true
3105
- * matchesDriftReachability('birth', stale) // false
3060
+ * matchesArtifactDriftReachability('birth', aligned) // true
3061
+ * matchesArtifactDriftReachability('birth', stale) // false
3106
3062
  * ```
3107
3063
  */
3108
- export declare function matchesDriftReachability(ownership: Ownership, finding: Finding): boolean;
3064
+ export declare function matchesArtifactDriftReachability(ownership: Ownership, finding: ArtifactFinding): boolean;
3109
3065
 
3110
3066
  /**
3111
3067
  * Tests whether a declared engines floor is at or above the supported minimum.
@@ -3330,7 +3286,7 @@ export declare class Compiler implements CompilerInterface {
3330
3286
  * the cause and no bytes. Either way `observed` is the local mirror's exact
3331
3287
  * bytes as they stood when the fetch was made, and is absent when the mirror
3332
3288
  * was not there; it is the precondition the write is held to, exactly as
3333
- * {@link Finding.observed} is. Whether the mirror is behind is not recorded,
3289
+ * {@link ArtifactFinding.observed} is. Whether the mirror is behind is not recorded,
3334
3290
  * because it is `content` against `observed` and a stored answer could only
3335
3291
  * disagree with them. These bytes belong to the catalog verb, which is why a
3336
3292
  * guide mirror is presence-owned: repair restores one that is absent and never
@@ -3477,6 +3433,27 @@ export declare class Compiler implements CompilerInterface {
3477
3433
  */
3478
3434
  export declare type Ownership = 'content' | 'presence' | 'birth';
3479
3435
 
3436
+ /**
3437
+ * Coerces an untrusted value to a group selection.
3438
+ *
3439
+ * @param value - The value to parse.
3440
+ * @returns The selection, or `undefined` when the value is not one.
3441
+ *
3442
+ * @remarks
3443
+ * Derived from {@link isArtifactGroups}. Order and repetition are preserved: which
3444
+ * groups a plan finally covers, and in which order, is the compiler's to decide
3445
+ * from `ARTIFACT_GROUPS`, not this boundary's.
3446
+ *
3447
+ * @example
3448
+ * ```ts
3449
+ * import { parseArtifactGroups } from '@orkestrel/scaffold'
3450
+ *
3451
+ * parseArtifactGroups(['manifest', 'configs']) // ['manifest', 'configs']
3452
+ * parseArtifactGroups(['readme']) // undefined
3453
+ * ```
3454
+ */
3455
+ export declare function parseArtifactGroups(value: unknown): readonly ArtifactGroup[] | undefined;
3456
+
3480
3457
  /**
3481
3458
  * Coerces an untrusted value to a {@link Blueprint}.
3482
3459
  *
@@ -3535,25 +3512,48 @@ export declare class Compiler implements CompilerInterface {
3535
3512
  export declare function parseExtension(value: unknown): Extension | undefined;
3536
3513
 
3537
3514
  /**
3538
- * Coerces an untrusted value to a group selection.
3515
+ * Snapshots an untrusted value into exact JSON data the caller owns.
3539
3516
  *
3540
- * @param value - The value to parse.
3541
- * @returns The selection, or `undefined` when the value is not one.
3517
+ * @param value - The untrusted value to take ownership of.
3518
+ * @returns A deeply frozen copy sharing nothing with `value`, or `undefined`
3519
+ * when the value is not exact acyclic JSON data.
3542
3520
  *
3543
3521
  * @remarks
3544
- * Derived from {@link isGroups}. Order and repetition are preserved: which
3545
- * groups a plan finally covers, and in which order, is the compiler's to decide
3546
- * from `GROUPS`, not this boundary's.
3522
+ * This fixes the order every boundary in this package reads a caller's value
3523
+ * in: snapshot first, then guard the snapshot. A guard reads `value[key]`, so a
3524
+ * property backed by an accessor can answer one thing while the guard runs and
3525
+ * another while the accepted value is used, and no guard closes that race from
3526
+ * inside. The snapshot closes it. The installed `cloneJSONValue` refuses any
3527
+ * property that is not an own enumerable data property, so an accessor never
3528
+ * reaches the guard at all, and it reads every value it keeps exactly once from
3529
+ * that property's descriptor. What the guard measures is what every later read
3530
+ * returns.
3531
+ *
3532
+ * The result is a frozen null-prototype record or a frozen intrinsic array, and
3533
+ * this package's guards accept both, so the snapshot passes `isBlueprint`,
3534
+ * `isSnapshot`, and the parsers derived from them unchanged.
3535
+ *
3536
+ * Ownership is refused rather than raised. A value carrying a function, an
3537
+ * `undefined`, a symbol key, a cycle, a non-finite number, or more nodes than
3538
+ * `@orkestrel/contract` admits answers `undefined`, which leaves each caller
3539
+ * free to decide what a refusal means — the compiler throws `INVALID`, the gate
3540
+ * asks a `Question` — and keeps `ScaffoldError` the only error this package
3541
+ * throws.
3542
+ *
3543
+ * The node ceiling is the installed package's `CLONE_NODE_LIMIT`, and it counts
3544
+ * every record, array, and leaf the snapshot would contain, so it bounds breadth
3545
+ * and depth together. This package declares no ceiling of its own beside it: a
3546
+ * local number no code here can enforce could only disagree with the one that
3547
+ * binds.
3547
3548
  *
3548
3549
  * @example
3549
3550
  * ```ts
3550
- * import { parseGroups } from '@orkestrel/scaffold'
3551
+ * import { parseBlueprint, parseOwnedJSONValue } from '@orkestrel/scaffold'
3551
3552
  *
3552
- * parseGroups(['manifest', 'configs']) // ['manifest', 'configs']
3553
- * parseGroups(['readme']) // undefined
3553
+ * const owned = parseBlueprint(parseOwnedJSONValue(input))
3554
3554
  * ```
3555
3555
  */
3556
- export declare function parseGroups(value: unknown): readonly Group[] | undefined;
3556
+ export declare function parseOwnedJSONValue(value: unknown): JSONValue | undefined;
3557
3557
 
3558
3558
  /**
3559
3559
  * Coerces an untrusted value to a {@link Snapshot}.
@@ -3609,7 +3609,7 @@ export declare class Compiler implements CompilerInterface {
3609
3609
  */
3610
3610
  export declare interface Plan {
3611
3611
  readonly blueprint: Blueprint;
3612
- readonly groups: readonly Group[];
3612
+ readonly groups: readonly ArtifactGroup[];
3613
3613
  readonly artifacts: readonly Artifact[];
3614
3614
  readonly hash?: string;
3615
3615
  }
@@ -3619,7 +3619,7 @@ export declare class Compiler implements CompilerInterface {
3619
3619
  readonly name: string;
3620
3620
  readonly src: readonly Environment[];
3621
3621
  readonly app: readonly Environment[];
3622
- readonly groups: readonly Group[];
3622
+ readonly groups: readonly ArtifactGroup[];
3623
3623
  readonly host: number;
3624
3624
  readonly template: number;
3625
3625
  readonly computed: number;
@@ -3644,14 +3644,14 @@ export declare class Compiler implements CompilerInterface {
3644
3644
  *
3645
3645
  * @example
3646
3646
  * ```ts
3647
- * import { Compiler, createBlueprint, planToFindings } from '@orkestrel/scaffold'
3647
+ * import { Compiler, createBlueprint, planToArtifactFindings } from '@orkestrel/scaffold'
3648
3648
  *
3649
3649
  * const { plan } = new Compiler().compile(createBlueprint('router', { src: ['core'] }))
3650
3650
  *
3651
- * plan === undefined ? [] : planToFindings(plan, { 'AGENTS.md': '68690a' })
3651
+ * plan === undefined ? [] : planToArtifactFindings(plan, { 'AGENTS.md': '68690a' })
3652
3652
  * ```
3653
3653
  */
3654
- export declare function planToFindings(plan: Plan, current: Snapshot): readonly Finding[];
3654
+ export declare function planToArtifactFindings(plan: Plan, current: Snapshot): readonly ArtifactFinding[];
3655
3655
 
3656
3656
  /**
3657
3657
  * Computes a plan's content identity.
@@ -4021,24 +4021,24 @@ export declare class Compiler implements CompilerInterface {
4021
4021
  * Selects the groups a compile covers, in plan order.
4022
4022
  *
4023
4023
  * @param groups - The requested selection; every group when absent.
4024
- * @returns The requested groups in `GROUPS` order, without repeats.
4024
+ * @returns The requested groups in `ARTIFACT_GROUPS` order, without repeats.
4025
4025
  *
4026
4026
  * @remarks
4027
4027
  * A caller's selection is data, so it arrives in whatever order and with
4028
4028
  * whatever repeats the caller wrote. Plan order is this package's, so the
4029
- * selection is read as membership and the order comes from `GROUPS`. An empty
4029
+ * selection is read as membership and the order comes from `ARTIFACT_GROUPS`. An empty
4030
4030
  * selection covers nothing, which is a caller asking for an empty plan rather
4031
4031
  * than a caller asking for everything.
4032
4032
  *
4033
4033
  * @example
4034
4034
  * ```ts
4035
- * import { selectGroups } from '@orkestrel/scaffold'
4035
+ * import { selectArtifactGroups } from '@orkestrel/scaffold'
4036
4036
  *
4037
- * selectGroups(['tests', 'manifest', 'tests']) // ['manifest', 'tests']
4038
- * selectGroups() // every group, in plan order
4037
+ * selectArtifactGroups(['tests', 'manifest', 'tests']) // ['manifest', 'tests']
4038
+ * selectArtifactGroups() // every group, in plan order
4039
4039
  * ```
4040
4040
  */
4041
- export declare function selectGroups(groups?: readonly Group[]): readonly Group[];
4041
+ export declare function selectArtifactGroups(groups?: readonly ArtifactGroup[]): readonly ArtifactGroup[];
4042
4042
 
4043
4043
  /**
4044
4044
  * Selects the host paths a named workspace vendors.