@orkestrel/scaffold 0.0.123 → 0.0.125

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 (51) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
  3. package/dist/bin/main.js +18 -18
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +5 -1
  6. package/dist/host/agents/platforms/windows.md +9 -1
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
  10. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
  12. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  14. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
  15. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
  17. package/dist/host/claude/agents/orkestrel.md +45 -45
  18. package/dist/host/claude/rules/patterns.md +1 -1
  19. package/dist/host/claude/rules/portability.md +2 -0
  20. package/dist/host/claude/rules/quality.md +3 -1
  21. package/dist/host/claude/rules/tests.md +3 -1
  22. package/dist/host/guides/agent.md +349 -244
  23. package/dist/host/guides/brief.md +52 -48
  24. package/dist/host/guides/browser.md +2 -2
  25. package/dist/host/guides/contract.md +226 -104
  26. package/dist/host/guides/database.md +12 -12
  27. package/dist/host/guides/interpret.md +531 -155
  28. package/dist/host/guides/mcp.md +183 -61
  29. package/dist/host/guides/ndjson.md +47 -34
  30. package/dist/host/guides/ollama.md +123 -66
  31. package/dist/host/guides/program.md +117 -39
  32. package/dist/host/guides/qualifier.md +110 -59
  33. package/dist/host/guides/rater.md +85 -32
  34. package/dist/host/guides/reason.md +377 -114
  35. package/dist/host/guides/scaffold.md +20 -12
  36. package/dist/host/guides/study.md +580 -483
  37. package/dist/host/guides/tool.md +163 -58
  38. package/dist/host/guides/toolbox.md +159 -80
  39. package/dist/host/guides/workflow.md +44 -25
  40. package/dist/host/manifest.json +41 -35
  41. package/dist/src/core/index.cjs +17 -17
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.js +17 -17
  44. package/dist/src/core/index.js.map +1 -1
  45. package/dist/src/server/index.cjs +23 -11
  46. package/dist/src/server/index.cjs.map +1 -1
  47. package/dist/src/server/index.d.cts +10 -6
  48. package/dist/src/server/index.d.ts +10 -6
  49. package/dist/src/server/index.js +23 -11
  50. package/dist/src/server/index.js.map +1 -1
  51. package/package.json +17 -17
@@ -11,8 +11,10 @@ matching line before the first rating call. Omitting `rating` authors a
11
11
  first-class eligibility-only program — the rater is never invoked, an eligible
12
12
  subject resolves to `'eligible'` (or `'conditional'` under an applied condition),
13
13
  and status is never `'unrated'`; an authored rating with zero lines still yields
14
- `'unrated'`, unchanged. The rater always receives the original subject;
15
- qualification and aggregate working projections stay private to orchestration.
14
+ `'unrated'`, unchanged. A definition's `shape` is read at the door before anything else reads the
15
+ subject, and missing information reads `'incomplete'` with eligibility `'referral'` and no decision.
16
+ The rater always receives what the door admitted; qualification and aggregate working projections
17
+ stay private to orchestration.
16
18
  `Program` executes synchronously. Its result is repeatable only while inputs and
17
19
  options stay unchanged and dependency behavior remains unchanged and deterministic.
18
20
 
@@ -22,7 +24,8 @@ delegating eligibility to `Qualifier`, amounts and worksheets to `Rater`, and
22
24
  logical or quantitative mechanics to the shared `@orkestrel/reason` engine behind
23
25
  them. Every output is a fresh `ProgramResult` or `AggregateResult` carrying the
24
26
  nested qualification and rating evidence, program determinations, trace, errors,
25
- status, and optional decision. `Program` either receives injected qualifier,
27
+ status, optional decision, and the `faults`, `repairs`, and `defaulted` a caller asks and reports from.
28
+ `Program` either receives injected qualifier,
26
29
  rater, and engine instances (never destroyed by `Program`) or creates and owns
27
30
  one shared quantitative-plus-logical engine (`bail: false`), destroyed in
28
31
  `destroy()`. Every `execute` call fires through `Program`'s typed `emitter`.
@@ -129,18 +132,18 @@ manager.destroy()
129
132
  | `Status` | type | `(typeof STATUSES)[number]` | Identifies the presentation and tally status derived from eligibility, conditions, and rating success. |
130
133
  | `ProgramEffect` | type | `'notice' \| 'limit'` | Identifies a post-qualification program determination effect. |
131
134
  | `ProgramErrorCode` | type | `'DUPLICATE' \| 'MISSING' \| 'DEFINITION' \| 'MISMATCH' \| 'RESERVED' \| 'DESTROYED'` | Identifies a coded `ProgramError` programmer-error code. |
132
- | `ProgramInput` | interface | `{ description?, notices?, authority?, aggregate?, metadata? }` | Describes the optional fields accepted by `buildProgramDefinition`. |
135
+ | `ProgramInput` | interface | `{ description?, notices?, authority?, aggregate?, metadata?, shape? }` | Describes the optional fields accepted by `buildProgramDefinition`. |
133
136
  | `NoticeInput` | interface | `{ scope? }` | Describes the optional fields accepted by `buildNotice`. |
134
137
  | `AggregateInput` | interface | `{ partition?, gates? }` | Describes the optional fields accepted by `buildAggregateDefinition`. |
135
138
  | `Notice` | interface | `{ id, message, scope? }` | Describes an authored, unconditional program notice. |
136
- | `Determination` | interface | `{ id, effect, applied, scope?, message?, premises }` | Describes one resolved notice or authority-limit outcome. |
139
+ | `Determination` | interface | `{ id, effect, state, scope?, message?, premises }` | Describes one resolved notice or authority-limit outcome. |
137
140
  | `AggregateDefinition` | interface | `{ fields, partition?, gates? }` | Describes batch aggregate fields, an optional partition field, and optional gates. |
138
141
  | `AggregateProjection` | interface | `{ count, sums, group? }` | Describes one subject's private aggregate working projection. |
139
142
  | `AggregateGroup` | interface | `{ key, count, sums }` | Describes one batch aggregate partition. |
140
143
  | `Tally` | interface | `{ count, sums }` | Describes a status tally — a count plus summed aggregate fields. |
141
- | `ProgramDefinition` | interface | `{ id, name, description?, qualification, rating?, notices?, authority?, aggregate?, metadata? }` | Describes a pure authored program definition. |
142
- | `ProgramResult` | interface | `{ id, name, eligibility, status, decision?, qualification, rating?, determinations, success, trace, errors }` | Describes one subject's complete program outcome. |
143
- | `AggregateResult` | interface | `{ id, name, subjects, determinations, groups, tallies, count, sums, success, trace, errors }` | Describes a batch program outcome across every subject. |
144
+ | `ProgramDefinition` | interface | `{ id, name, description?, qualification, rating?, notices?, authority?, aggregate?, metadata?, shape? }` | Describes a pure authored program definition. |
145
+ | `ProgramResult` | interface | `{ id, name, eligibility, status, decision?, qualification, rating?, determinations, success, trace, errors, faults, repairs, defaulted }` | Describes one subject's complete program outcome. |
146
+ | `AggregateResult` | interface | `{ id, name, subjects, determinations, groups, tallies, count, sums, success, trace, errors, faults, repairs, defaulted }` | Describes a batch program outcome across every subject. |
144
147
  | `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`. |
145
148
  | `ProgramOptions` | interface | `{ qualifier?, rater?, engine?, validate?, labels?, on?, error? }` | Describes the options for `createProgram` / the `Program` constructor. |
146
149
  | `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. |
@@ -158,13 +161,15 @@ rater supplies `RatingDefinition` and `RatingResult`; reason supplies
158
161
 
159
162
  ### Constants
160
163
 
161
- | Name | Kind | Signature | Summary |
162
- | -------------------------- | ----- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
163
- | `DEFAULT_PROGRAM_VALIDATE` | const | `true` | Names the default definition validation policy, `true`, for `createProgram` / `ProgramManager.add`. |
164
- | `STATUSES` | const | `readonly ["ineligible", "referral", "conditional", "unrated", "eligible"]` | Lists every `Status` literal in tally order — the source the union and its guard derive from. |
165
- | `ELIGIBILITY_DECISIONS` | const | `Readonly<Record<Eligibility, Decision>>` | Maps each global eligibility to its deterministic authority decision. |
166
- | `AGGREGATE_KEY` | const | `"aggregate"` | Names the reserved working-subject key a batch's aggregate projection is written under, `'aggregate'`. |
167
- | `OUTCOME_KEY` | const | `"outcome"` | Names the reserved working-subject key the authority's outcome projection is written under, `'outcome'`. |
164
+ | Name | Kind | Signature | Summary |
165
+ | -------------------------- | ----- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
166
+ | `PROGRAM_EFFECTS` | const | `readonly ProgramEffect[]` | Lists every `ProgramEffect` literal, the source the determination shape reads. |
167
+ | `DECISIONS` | const | `readonly Decision[]` | Lists every `Decision` literal, the source the decision shape reads. |
168
+ | `DEFAULT_PROGRAM_VALIDATE` | const | `true` | Names the default definition validation policy, `true`, for `createProgram` / `ProgramManager.add`. |
169
+ | `STATUSES` | const | `readonly ["ineligible", "referral", "incomplete", "conditional", "unrated", "eligible"]` | Lists every `Status` literal in tally order — the source the union and its guard derive from. |
170
+ | `ELIGIBILITY_DECISIONS` | const | `Readonly<Record<Eligibility, Decision>>` | Maps each global eligibility to its deterministic authority decision. |
171
+ | `AGGREGATE_KEY` | const | `"aggregate"` | Names the reserved working-subject key a batch's aggregate projection is written under, `'aggregate'`. |
172
+ | `OUTCOME_KEY` | const | `"outcome"` | Names the reserved working-subject key the authority's outcome projection is written under, `'outcome'`. |
168
173
 
169
174
  `STATUSES` and `ELIGIBILITY_DECISIONS` are `Object.freeze`d; the reserved keys and
170
175
  the validation default are primitives. The reserved keys exist only for composed
@@ -250,7 +255,7 @@ isStatus('conditional') // true
250
255
  isNotice({ id: 'file', message: 'Subject retained for audit' }) // true
251
256
  isAggregateDefinition({ fields: ['amount'], partition: 'location' }) // true
252
257
  isProgramDefinition(definition) // true
253
- isDetermination({ id: 'audit', effect: 'notice', applied: true, premises: [] }) // true
258
+ isDetermination({ id: 'audit', effect: 'notice', state: 'met', premises: [] }) // true
254
259
  isProgramResult(program.execute(subject)) // true
255
260
  isAggregateResult(program.execute(subjects)) // true
256
261
  ```
@@ -264,18 +269,26 @@ The program helpers are pure orchestration leaves. They do not reproduce qualifi
264
269
  rater, or reason logic — message interpolation and rich premise construction for
265
270
  authority and aggregate-gate rules reuse `@orkestrel/qualifier`'s own
266
271
  `interpolateMessage`, `findRule`, and `ruleToPremises` (all public qualifier exports,
267
- generic over any `Rule`/`Subject`/`EvaluatorInterface`) rather than re-implementing
268
- them. `Program` owns one stateless `#evaluator` (created with `createEvaluator()`,
269
- never destroyed — it holds no state to tear down) purely to drive that reuse.
272
+ generic over any `Rule`) rather than re-implementing them, so a premise reports what the rule
273
+ itself read.
270
274
 
271
275
  | Name | Kind | Signature | Summary |
272
276
  | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
277
+ | `projectAggregateResult` | function | `(result: AggregateResult) => JSONValue \| undefined` | Projects a batch result to the JSON its contract reads. |
278
+ | `projectProgramResult` | function | `(result: ProgramResult) => JSONValue \| undefined` | Projects a result to the JSON its contract reads. |
279
+ | `scanProgramShape` | function | `(definition: ProgramDefinition) => ShapeScan` | Describes what is wrong with a program's shape, against the program itself. |
280
+ | `findAggregateGap` | function | `(shape: ContractShape, field: FieldPath) => string \| undefined` | Reads what a shape says about an aggregate field or the partition. |
281
+ | `buildRefusedQualification` | function | `(definition: QualificationDefinition, admission: SubjectAdmission) => QualificationResult` | Builds the qualification a subject refused at the program's door stands in for. |
282
+ | `matchesNumberField` | function | `(shape: ContractShape, field: FieldPath) => boolean` | Determines whether a field a shape declares can only hold a number a sum can read. |
283
+ | `isSettledResult` | function | `(result: LogicalResult) => boolean` | Determines whether a borrowed authority or gate read everything it needed. |
284
+ | `isDefinitionRefusal` | function | `(error: unknown) => boolean` | Determines whether an error says a borrowed part refused a definition. |
285
+ | `isInputFault` | function | `(fault: AuditFault) => boolean` | Determines whether a fault names an input a question can be asked about. |
273
286
  | `selectProgramLines` | function | `(lines: readonly LineDefinition[], scopes: Readonly<Record<string, Eligibility>>) => readonly LineDefinition[]` | Selects the rating lines a subject may be rated on from scoped eligibility. |
274
287
  | `deriveStatus` | function | `(definition: ProgramDefinition, qualification: QualificationResult, rating?: RatingResult) => Status` | Derives the final program `Status` from a definition's rating policy and qualification/rating evidence. |
275
288
  | `decideEligibility` | function | `(eligibility: Eligibility) => Decision` | Maps a global `Eligibility` to its deterministic authority `Decision`. |
276
289
  | `buildNoticeDeterminations` | function | `(notices: readonly Notice[], subject: Readonly<Record<string, unknown>>) => readonly Determination[]` | Resolves authored `Notice` values into unconditionally-applied `notice` `Determination` values. |
277
- | `buildLimitDeterminations` | function | `(definition: LogicalDefinition, result: LogicalResult, working: Readonly<Record<string, unknown>>, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>) => readonly Determination[]` | Converts a logical result's applied rules into `limit` `Determination` values. |
278
- | `buildProgramResult` | function | `(definition: ProgramDefinition, qualification: QualificationResult, rating: RatingResult \| undefined, determinations: readonly Determination[], status: Status, options?: { readonly authority?: LogicalResult; }) => ProgramResult` | Assembles a `ProgramResult` from its qualification, rating, and determination parts — before or after authority. |
290
+ | `buildLimitDeterminations` | function | `(definition: LogicalDefinition, result: LogicalResult, working: Readonly<Record<string, unknown>>, labels?: Readonly<Record<string, string>>) => readonly Determination[]` | Converts a logical result's applied rules into `limit` `Determination` values. |
291
+ | `buildProgramResult` | function | `(definition: ProgramDefinition, qualification: QualificationResult, rating: RatingResult \| undefined, determinations: readonly Determination[], status: Status, options?: { readonly authority?: LogicalResult; readonly admission?: SubjectAdmission; }) => ProgramResult` | Assembles a `ProgramResult` from its qualification, rating, and determination parts — before or after authority. |
279
292
  | `buildOutcomeProjection` | function | `(result: ProgramResult) => Readonly<Record<string, unknown>>` | Builds the private authority outcome projection from an assembled program result. |
280
293
  | `buildQualificationSubject` | function | `(subject: Subject, aggregate?: AggregateProjection) => Subject` | Adds optional aggregate context to a private subject copy for qualification. |
281
294
  | `findMissingScopes` | function | `(definition: ProgramDefinition) => readonly string[]` | Returns authored scopes (qualification ruling scopes or notice scopes) that name no rating line on the program. |
@@ -359,10 +372,11 @@ const definition = buildProgramDefinition('standard', 'Standard', qualification,
359
372
 
360
373
  ### Factories
361
374
 
362
- | Name | Kind | Signature | Summary |
363
- | ---------------------- | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
364
- | `createProgram` | function | `(definition: ProgramDefinition, options?: ProgramOptions) => ProgramInterface` | Creates one compiled `ProgramInterface` over a qualifier and rater. |
365
- | `createProgramManager` | function | `(options?: ProgramManagerOptions) => ProgramManagerInterface` | Creates one ordered `ProgramManagerInterface` over compiled programs. |
375
+ | Name | Kind | Signature | Summary |
376
+ | --------------------------------- | -------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
377
+ | `createProgramDefinitionContract` | function | `() => ContractInterface<unknown>` | Creates a `ProgramDefinition` as a contract. Cross it on `is`, never `parse`. |
378
+ | `createProgram` | function | `(definition: ProgramDefinition, options?: ProgramOptions) => ProgramInterface` | Creates one compiled `ProgramInterface` over a qualifier and rater. |
379
+ | `createProgramManager` | function | `(options?: ProgramManagerOptions) => ProgramManagerInterface` | Creates one ordered `ProgramManagerInterface` over compiled programs. |
366
380
 
367
381
  The factories compile entities. The authored definitions they compile are plain
368
382
  values, so their builders are helper leaves rather than factories.
@@ -385,6 +399,29 @@ program.destroy()
385
399
  manager.destroy()
386
400
  ```
387
401
 
402
+ ### Shapes
403
+
404
+ The definition and results as `ContractShape` values.
405
+
406
+ | Name | Kind | Signature | Summary |
407
+ | ------------------------------ | -------- | --------------------- | ------------------------------------------------------ |
408
+ | `aggregateResultShape` | const | `ContractShape` | Describes an `AggregateResult` in its JSON projection. |
409
+ | `tallyShape` | const | `ContractShape` | Describes a `Tally` in its JSON projection. |
410
+ | `programSumsShape` | const | `ContractShape` | Describes a sums record in its JSON projection. |
411
+ | `programResultShape` | const | `ContractShape` | Describes a `ProgramResult` in its JSON projection. |
412
+ | `determinationShape` | const | `ContractShape` | Describes a `Determination` in its JSON projection. |
413
+ | `createProgramDefinitionShape` | function | `() => ContractShape` | Creates the shape of a `ProgramDefinition`. |
414
+ | `noticeShape` | const | `ContractShape` | Describes a `Notice`. |
415
+
416
+ ### Contracts
417
+
418
+ The compiled contracts of what is flat enough to compile at import.
419
+
420
+ | Name | Kind | Signature | Summary |
421
+ | ------------------------- | ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
422
+ | `aggregateResultContract` | const | `ContractInterface<unknown>` | Publishes an `AggregateResult`'s JSON projection as a contract, read through `projectAggregateResult`. |
423
+ | `programResultContract` | const | `ContractInterface<unknown>` | Publishes a `ProgramResult`'s JSON projection as a contract, read through `projectProgramResult`. |
424
+
388
425
  ### Classes
389
426
 
390
427
  | Name | Kind | Signature | Summary |
@@ -468,18 +505,21 @@ keeps execution and collection responsibilities separate.
468
505
  For one subject:
469
506
 
470
507
  1. assert subject shape and reserved-key safety
471
- 2. qualify against the optional private aggregate projection
472
- 3. emit `qualify`
508
+ 2. admit the subject at the door, and on a refusal emit `qualify` with what the door said and go
509
+ to step 10 with nothing rated
510
+ 3. qualify what it admitted against the optional private aggregate projection
511
+ and emit `qualify`
473
512
  4. stop if qualification failed
474
513
  5. stop if global eligibility is `ineligible` or `referral`
475
514
  6. select rating lines from scoped eligibility
476
515
  7. skip rating when no line remains
477
- 8. rate the selected lines against the original subject
516
+ 8. rate the selected lines against what the door admitted
478
517
  9. emit `rate`
479
518
  10. build notices
480
519
  11. derive status
481
520
  12. build the preliminary program result
482
- 13. run optional authority against the private outcome projection
521
+ 13. run optional authority against the private outcome projection, unless the status is
522
+ `incomplete`, whose outcome holds no answer to read
483
523
  14. build and emit limit determinations
484
524
  15. derive the optional decision
485
525
  16. emit `decide` when present
@@ -584,14 +624,15 @@ approved-with-conditions and denied — a scoped restriction can yield
584
624
 
585
625
  For a subject array:
586
626
 
587
- 1. validate every subject and reserved key
627
+ 1. validate every subject and reserved key, and admit each at the door
588
628
  2. collect aggregate fields from `definition.aggregate`
589
- 3. compute overall sums
590
- 4. compute optional groups
591
- 5. build each subject's aggregate projection
629
+ 3. compute overall sums from what the door admitted
630
+ 4. compute optional groups the same way
631
+ 5. build each subject's aggregate projection, unless the door refused a subject
592
632
  6. execute subjects in input order
593
633
  7. tally every result by status
594
- 8. run optional aggregate gates against the batch aggregate record (`count`, `sums`, `groups`)
634
+ 8. run optional aggregate gates against the batch aggregate record (`count`, `sums`, `groups`),
635
+ unless the door refused a subject
595
636
  9. convert applied rules to batch `limit` determinations
596
637
  10. emit `aggregate`
597
638
 
@@ -601,6 +642,10 @@ The aggregate-gate evaluation's `trace` and `errors` fold into
601
642
  no errors — a gate evaluation failure fails the batch result even when every subject
602
643
  execution succeeded.
603
644
 
645
+ While the door has refused any subject the sums are not the batch's, so no subject reads the
646
+ `aggregate` projection and no gate runs. Such a batch fails, and its `sums` hold only what was
647
+ admitted.
648
+
604
649
  Batch aggregation does not modify individual rating subjects.
605
650
 
606
651
  ### Aggregate projection
@@ -629,11 +674,18 @@ carries either key is rejected with `ProgramError('RESERVED')` before qualificat
629
674
  Status is explicit policy, not an opaque severity reducer. It resolves in this order:
630
675
 
631
676
  1. global ineligible
632
- 2. global or scoped referral
633
- 3. `ProgramDefinition.rating` is omitted (eligibility-only program) → `conditional` under an applied condition or scoped restriction, otherwise `eligible`, never `unrated`
634
- 4. no successful rating, an authored rating with zero lines included → `unrated`
635
- 5. applied condition or scoped restriction → `conditional`
636
- 6. otherwise → `eligible`
677
+ 2. a fault on an input the answer needs → `incomplete`, with eligibility `referral` and no decision
678
+ 3. global or scoped referral
679
+ 4. `ProgramDefinition.rating` is omitted (eligibility-only program) → `conditional` under an applied condition or scoped restriction, otherwise `eligible`, never `unrated`
680
+ 5. no successful rating, an authored rating with zero lines included → `unrated`
681
+ 6. applied condition or scoped restriction → `conditional`
682
+ 7. otherwise → `eligible`
683
+
684
+ `incomplete` is the question a caller can answer, and `faults` names what to ask for: the door's
685
+ refusals, and any input a rule or a factor could not read. A later restriction still outranks it.
686
+ `referral` stays what a rule refers. A read of the `aggregate` projection is the program's own, so it
687
+ fails the run and asks nobody, and so does anything an authority could not read: write
688
+ `and(outcome.rated equals true, outcome.total above 100)` so the read is only reached when it holds.
637
689
 
638
690
  ### Decision
639
691
 
@@ -647,12 +699,31 @@ Status is explicit policy, not an opaque severity reducer. It resolves in this o
647
699
 
648
700
  No decision is emitted without an authority definition.
649
701
 
702
+ ### The door
703
+
704
+ `ProgramDefinition.shape` declares the subject, and a program is its one root: a qualification, a
705
+ rating, or a line carrying a shape of its own is a `validate` error, because the program has already
706
+ read the subject once. An authority and an aggregate's `gates` keep theirs, because they read a
707
+ projection. With a shape, `validate` also refuses a field a pass, a line, or a notice reads that the
708
+ shape does not declare, and an aggregate field or partition that may be absent or `null` with no
709
+ default, because a sum would skip it and a partition would pool it. `validate` refuses an authority
710
+ over a qualification with no passes, which has nothing to decide on. A program that only rates is
711
+ allowed.
712
+
713
+ An `AggregateResult` gathers its subjects' `faults`, `repairs`, and `defaulted`, each once by path, and
714
+ each subject keeps its own. A result crosses a boundary as `projectProgramResult` or
715
+ `projectAggregateResult`, which `programResultContract` and `aggregateResultContract` admit. A
716
+ definition crosses on `createProgramDefinitionContract().is`, never `parse`. `is` reads a nested
717
+ `shape` as any JSON value and the guard reads it as a shape, so `shape: 42` passes `is` and
718
+ `isProgramDefinition` refuses it: a definition crossing a boundary goes through the guard as well.
719
+
650
720
  ### Success
651
721
 
652
722
  `ProgramResult.success` indicates execution integrity:
653
723
 
654
724
  - valid ineligibility can succeed
655
725
  - valid referral can succeed
726
+ - an `incomplete` result fails
656
727
  - qualification errors fail
657
728
  - rating errors fail
658
729
  - authority errors fail
@@ -711,6 +782,13 @@ owned emitter.
711
782
 
712
783
  ### Validation
713
784
 
785
+ The program's subject shape cannot declare `outcome`, `aggregate`, or a qualification rule's
786
+ conclusion field. Ruling message tokens are checked against that root shape. An authority reads
787
+ only the computed outcome projection or its own derived conclusions; subject fields and unknown
788
+ outcome fields are refused at validation. The projection declares `id`, `eligibility`, `status`,
789
+ `rated`, `total`, and `scopes` keyed by rating-line id. A declared field can still be absent at
790
+ execution: `total` is absent when rating did not run, and an unread authority produces no decision.
791
+
714
792
  `Program.validate` (`validateProgramDefinition`) checks:
715
793
 
716
794
  1. exact shape through `isProgramDefinition` — this alone establishes rating structure and authority/gates shape, so validate performs no redundant re-check of either