@mark1russell7/coeval 0.6.3 → 0.7.1

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/build/index.d.ts CHANGED
@@ -162,7 +162,7 @@ export declare function docEquals(a: unknown, b: unknown): boolean;
162
162
  //#endregion
163
163
  //#region src/errors.d.ts
164
164
  /** The codes that the kernel gives. */
165
- type KernelCode = "#KIND?" | "#NOEVAL" | "#PART?" | "#NAME?" | "#REF!" | "#N/A" | "#CYCLE!" | "#STEP?" | "#VALUE!" | "#NUM!" | "#ARGS" | "#CAP!" | "#CALC!" | "#DEPTH!" | "#ABORT" | "#REPLAY!";
165
+ type KernelCode = "#KIND?" | "#NOEVAL" | "#PART?" | "#NAME?" | "#REF!" | "#N/A" | "#CYCLE!" | "#STEP?" | "#VALUE!" | "#NUM!" | "#ARGS" | "#CAP!" | "#CALC!" | "#DEPTH!" | "#ABORT" | "#REPLAY!" | "#TYPE!";
166
166
  /** The code of an error value. A language can add its own codes. Each code starts with `#`. */
167
167
  type ErrorCode = KernelCode | `#${string}`;
168
168
  /**
@@ -414,8 +414,10 @@ interface ResolveOptions {
414
414
  }
415
415
  /**
416
416
  * This function answers one step of a path on a thing, through the ladder of the verb `deref`. A host thing
417
- * answers for itself (own). A document asks its own entry, then its kind. The default goes into the value: an own
418
- * field of an object, or an item of a list.
417
+ * answers for itself (own). A document asks its own entry, then its kind, then the default of the world
418
+ * (VERB.LADDER). A rung answers only with a `deref` that the navigator has. When no rung answers, the step goes into
419
+ * the value: an own field of an object, or an item of a list. A value without a type is data, thus the step goes
420
+ * into it at once.
419
421
  *
420
422
  * @param nav - The world and the code of the evaluators.
421
423
  * @param thing - The thing that the path reached.
@@ -455,9 +457,9 @@ export declare function context(parts?: Partial<Context>): Context;
455
457
  * This function resolves a path from a context, and records each hop.
456
458
  *
457
459
  * The first step is a root of the context. Each later step is a key or a step document. A key goes up the ladder
458
- * of the verb `deref` on the thing that the path reached. A step document is evaluated by the walker of its kind,
459
- * with the thing that the path reached. After each hop, a reference document is followed until the path reaches
460
- * something else (collapse), except in a plain navigation.
460
+ * of the verb `deref` on the thing that the path reached. A step document is evaluated by the walker that the
461
+ * ladder of the verb `step` gives, with the thing that the path reached. After each hop, a reference document is
462
+ * followed until the path reaches something else (collapse), except in a plain navigation.
461
463
  *
462
464
  * The codes of a failure:
463
465
  *
@@ -482,6 +484,188 @@ export declare function resolve(nav: Navigator, ctx: Context, path: readonly unk
482
484
  */
483
485
  export declare function valueOfThing(thing: Thing): unknown;
484
486
  //#endregion
487
+ //#region src/types.d.ts
488
+ /**
489
+ * A value type: a set of values that a result can have, as a JSON term.
490
+ *
491
+ * - A text names a base type: `unknown`, `never`, a domain of the kernel (`null`, `bool`, `number`, `text`), or a
492
+ * domain of a language.
493
+ * - `list`: a list whose items have the type.
494
+ * - `record`: a plain record with the named fields. `optional` names the fields that can be absent. A `closed`
495
+ * record has no other fields. The other fields of an open record can hold each value.
496
+ * - `fn`: a function with the types of its parameters, and the type of its result (`to`).
497
+ * - `union`: a value of one of the types. An empty union holds no value.
498
+ * - `one`: one of the JSON values of the list.
499
+ *
500
+ * A term that is not in this list reads as `unknown` (TYPE.UNKNOWN). Thus a later version can add a term.
501
+ */
502
+ type ValueType = string | {
503
+ readonly list: ValueType;
504
+ } | {
505
+ readonly record: Readonly<Record<string, ValueType>>;
506
+ readonly optional?: readonly string[];
507
+ readonly closed?: boolean;
508
+ } | {
509
+ readonly fn: readonly ValueType[];
510
+ readonly to: ValueType;
511
+ } | {
512
+ readonly union: readonly ValueType[];
513
+ } | {
514
+ readonly one: readonly Json[];
515
+ };
516
+ /**
517
+ * A value domain: a base type of a language, with its membership test. A machine holds its domains by their names
518
+ * (`Machine.domains`). A value is a member of a domain only when the test of the domain and the test of each parent
519
+ * accept it (TYPE.MEMBER).
520
+ *
521
+ * A path does not follow a member of a domain as a reference (DEREF.COLLAPSE). Thus the test `is` must refuse each
522
+ * reference document.
523
+ */
524
+ interface Domain {
525
+ /**
526
+ * This function tells if a value is a member of the domain. It must be pure. A test that throws gives `false`.
527
+ *
528
+ * @param value - The value.
529
+ * @returns `true` for a member.
530
+ */
531
+ readonly is: (value: unknown) => boolean;
532
+ /** The names of the parents: the base types that hold each member of the domain. A base type fits each parent. */
533
+ readonly under?: readonly string[];
534
+ /** One sentence that tells what the domain holds. */
535
+ readonly summary?: string;
536
+ /**
537
+ * The value type of each step into a member, by its key, for example the field `x` of a point (TYPE.STEPS). The
538
+ * check of a path reads the steps of the domain first, then the steps of each parent. The language keeps them true:
539
+ * a step with the key into a member reaches a member of the type. A key without a type gives `unknown`.
540
+ */
541
+ readonly steps?: Readonly<Record<string, ValueType>>;
542
+ /**
543
+ * The codec of the members: it writes a member as JSON and reads it again (D40). A document holds a member as the
544
+ * standard extension `ext.domain`. A domain without a codec has no such document.
545
+ */
546
+ readonly codec?: DomainCodec;
547
+ }
548
+ /**
549
+ * The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
550
+ * must be pure. `decode(encode(v))` must equal `v` by `sameValue` (EXT.ROUNDTRIP). The codec must give one JSON
551
+ * value for each member, thus the same value has the same document in each language (D12).
552
+ */
553
+ interface DomainCodec {
554
+ /**
555
+ * This function writes a member of the domain as JSON.
556
+ *
557
+ * @param value - A member of the domain.
558
+ * @returns The JSON of the member.
559
+ */
560
+ readonly encode: (value: unknown) => Json;
561
+ /**
562
+ * This function reads the JSON of a member again. It throws for JSON that does not write a member.
563
+ *
564
+ * @param data - The JSON that `encode` gave.
565
+ * @returns The member.
566
+ */
567
+ readonly decode: (data: Json) => unknown;
568
+ }
569
+ /** A problem of a value type: the keys from the root of the term to the problem, and the reason. */
570
+ interface TypeIssue {
571
+ readonly at: readonly Key[];
572
+ readonly reason: string;
573
+ }
574
+ /**
575
+ * The domains of the kernel. `unknown` and `never` are not domains: they are the top and the bottom of the types.
576
+ * A machine that does not name one of these domains gets it from this table.
577
+ */
578
+ export declare const STD_DOMAINS: Readonly<Record<string, Domain>>;
579
+ /**
580
+ * This function tells if a value is a member of a value type (TYPE.MEMBER). It is the membership test that a cast
581
+ * at run time uses.
582
+ *
583
+ * - Each value is a member of `unknown`, and no value is a member of `never`.
584
+ * - A value is a member of a domain when the test `is` of the domain and of each parent accepts it.
585
+ * - A list, a record, a union and `one` test their values at each depth.
586
+ * - A function type tests only that the value is a function. Its parameters need a test at each call.
587
+ *
588
+ * The function does not throw. A term that is not a value type, or a base type without a domain, holds each value.
589
+ *
590
+ * @param value - The value.
591
+ * @param type - The value type.
592
+ * @param domains - The domains of the machine. A domain of the kernel that the table does not name comes from `STD_DOMAINS`.
593
+ * @returns `true` when the value is a member of the type.
594
+ */
595
+ export declare function member(value: unknown, type: ValueType, domains?: Readonly<Record<string, Domain>>): boolean;
596
+ /**
597
+ * This function tells if each value of the type `found` can be where the type `expected` must be (TYPE.FITS). Each
598
+ * check of a type uses it.
599
+ *
600
+ * - `unknown` fits each type, and each type fits `unknown` (TYPE.UNKNOWN). This is the gradual top.
601
+ * - `never` fits each type. Only `never`, an empty union and an empty `one` fit `never`.
602
+ * - A union fits when each of its types fits. A type fits a union when it fits one of its types.
603
+ * - `one` fits when each of its values is a member of `expected`.
604
+ * - A base type fits itself and each parent of its domain, through each level (TYPE.DOMAIN).
605
+ * - A list fits a list when its items fit.
606
+ * - A record fits a record with fewer fields. A field that `expected` needs is not optional in `found`, and each field
607
+ * fits. Only a closed record fits a closed record. An open record without an optional field fits only when that
608
+ * field is `unknown`.
609
+ * - A function fits when it has the same or fewer parameters, each expected parameter fits its parameter, and its
610
+ * result fits.
611
+ *
612
+ * The relation is sound: a member of `found` is a member of `expected` when no `unknown` is in the types. It is not
613
+ * complete. For example, `bool` does not fit `{ "one": [true, false] }`. The function does not throw.
614
+ *
615
+ * @param found - The type that a part has.
616
+ * @param expected - The type that the position needs.
617
+ * @param domains - The domains of the machine. A domain of the kernel that the table does not name comes from `STD_DOMAINS`.
618
+ * @returns `true` when `found` fits `expected`.
619
+ */
620
+ export declare function fits(found: ValueType, expected: ValueType, domains?: Readonly<Record<string, Domain>>): boolean;
621
+ /**
622
+ * This function gives the join of two value types (TYPE.JOIN): a type that holds each member of both types. The check
623
+ * of a type uses it for the branches of an `if` and for the items of a list.
624
+ *
625
+ * - `unknown` with each type gives `unknown`, and `never` with a type gives that type.
626
+ * - When one type fits the other by the strict form of `fits`, the join is the wider type. The strict form reads
627
+ * `unknown` only as the top.
628
+ * - Two lists give a list of the join of their items.
629
+ * - Two records give a record of the join of their common fields. A field of one closed record is optional in the
630
+ * join of two closed records. The join of an open record leaves out the fields that only one record has.
631
+ * - Each other pair gives a union. The union puts the values of `one` together and leaves out each member that fits
632
+ * another member.
633
+ *
634
+ * The join is sound: a member of `a` or of `b` is a member of the join. It is not always the least such type. The
635
+ * function does not throw.
636
+ *
637
+ * @param a - The first type.
638
+ * @param b - The second type.
639
+ * @param domains - The domains of the machine. A domain of the kernel that the table does not name comes from `STD_DOMAINS`.
640
+ * @returns The join.
641
+ */
642
+ export declare function join(a: ValueType, b: ValueType, domains?: Readonly<Record<string, Domain>>): ValueType;
643
+ /**
644
+ * This function gives the text of a value type (TYPE.TEXT), for the reason of an issue. The function does not throw.
645
+ *
646
+ * - A base type gives its name.
647
+ * - `list<T>` is a list, `{a: T, b?: U}` is a closed record, and `{a: T, ...}` is an open record.
648
+ * - `(T, U) => V` is a function, and `T | U` is a union.
649
+ * - `one` gives its values as JSON, and an empty union gives `never`.
650
+ * - A term that is not a value type gives `unknown`.
651
+ *
652
+ * The text shows at most 8 values of `one`, and it cuts a long value.
653
+ *
654
+ * @param type - The value type.
655
+ * @returns The text.
656
+ */
657
+ export declare function typeText(type: ValueType): string;
658
+ /**
659
+ * This function lists the problems of a value type (TYPE.ISSUES). A problem is a term that is not a value type, a
660
+ * base type without a domain, or a term that is too deep. `fits` and `member` read each such term as `unknown`.
661
+ * Thus a check that reads a type from a contract can report it first.
662
+ *
663
+ * @param type - The value type, as JSON.
664
+ * @param domains - The domains of the machine. A domain of the kernel that the table does not name comes from `STD_DOMAINS`.
665
+ * @returns The problems. A term comes before its parts, and the parts keep their order.
666
+ */
667
+ export declare function typeIssues(type: unknown, domains?: Readonly<Record<string, Domain>>): readonly TypeIssue[];
668
+ //#endregion
485
669
  //#region src/world.d.ts
486
670
  /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
487
671
  type Side = "derive" | "run";
@@ -501,6 +685,9 @@ type Side = "derive" | "run";
501
685
  * A `term` with `address: true` is an address: a reference there gives what its path reaches, not the value. A
502
686
  * `term` with `kinds` permits only a part whose type starts with one of the paths. A `record` with `closed: true`
503
687
  * permits only its named fields. A `list` with `distinct: true` permits no two equal items.
688
+ *
689
+ * `expect` is the value type that a part must have, as `of` is its type (TYPE.CHECK). A shape with parts gives it to
690
+ * each part that `of` covers. Only a check of types reads it, and it describes the verb `eval`.
504
691
  */
505
692
  type Shape = {
506
693
  readonly shape: "none";
@@ -509,15 +696,18 @@ type Shape = {
509
696
  readonly of?: string;
510
697
  readonly address?: boolean;
511
698
  readonly kinds?: readonly (readonly Key[])[];
699
+ readonly expect?: ValueType;
512
700
  } | {
513
701
  readonly shape: "list";
514
702
  readonly of?: string;
515
703
  readonly item?: Shape;
516
704
  readonly distinct?: boolean;
705
+ readonly expect?: ValueType;
517
706
  } | {
518
707
  readonly shape: "map";
519
708
  readonly of?: string;
520
709
  readonly item?: Shape;
710
+ readonly expect?: ValueType;
521
711
  } | {
522
712
  readonly shape: "record";
523
713
  readonly fields: readonly string[] | Readonly<Record<string, Shape>>;
@@ -525,9 +715,11 @@ type Shape = {
525
715
  readonly required?: readonly string[];
526
716
  readonly rest?: Shape;
527
717
  readonly closed?: boolean;
718
+ readonly expect?: ValueType;
528
719
  } | {
529
720
  readonly shape: "deep";
530
721
  readonly of?: string;
722
+ readonly expect?: ValueType;
531
723
  } | {
532
724
  readonly shape: "text";
533
725
  } | {
@@ -595,8 +787,44 @@ type CapsRule = {
595
787
  readonly caps: readonly Cap[];
596
788
  readonly in?: readonly (readonly Key[])[];
597
789
  };
598
- /** A kind gives the name of an evaluator for each verb, and the contract of its value. */
599
- interface Kind {
790
+ /**
791
+ * A lazy rule of a kind names the parts that an evaluation can skip and still give a value. An example is the
792
+ * branches of `if`. The static facts mark each read under such a part (D24).
793
+ *
794
+ * `in` names the parts, as patterns of their paths in the value. The key `"*"` matches each key. A rule without `in`
795
+ * covers each part. With `after: n`, the rule covers only the parts after the first `n` parts that its patterns
796
+ * match. Thus `{ after: 1 }` makes each part lazy except the first part, as in `and`.
797
+ */
798
+ interface LazyRule {
799
+ readonly in?: readonly (readonly Key[])[];
800
+ readonly after?: number;
801
+ }
802
+ /**
803
+ * The static facts that a kind declares for its code (D24). The contract of a kind holds them, and the hook `facts`
804
+ * of a machine can give them for a name under a fallback kind. The facts describe the code of `eval`, and of `step`
805
+ * for a step document.
806
+ *
807
+ * - `pure`: `true` when the code of the kind causes no effect. Its result depends only on its data, the results
808
+ * of its parts and what its paths reach. A kind that reads the context in another way does not declare it,
809
+ * because the static facts do not see that read.
810
+ * - `volatile`: `true` when its result can change while each read gives the same thing, for example a clock.
811
+ * - `lazy`: the parts that an evaluation can skip and still give a value.
812
+ */
813
+ interface KindFacts {
814
+ readonly pure?: boolean;
815
+ readonly volatile?: boolean;
816
+ readonly lazy?: readonly LazyRule[];
817
+ }
818
+ /**
819
+ * A kind gives the name of an evaluator for each verb, and the contract of its value. The contract serves each verb.
820
+ * For each verb, the kernel splits the parts and narrows their capabilities by it, and `check` reads its scope rules.
821
+ * `side` and `effects` tell what the verb `eval` does (VERB.CONTRACT).
822
+ */
823
+ interface Kind extends KindFacts {
824
+ /**
825
+ * The evaluator names, by verb. `eval` evaluates a document, `deref` answers a step on it, and `step` names the
826
+ * walker of a step document. A language adds its own verbs, for example `view` or `format`.
827
+ */
600
828
  readonly verbs: Readonly<Record<string, string>>;
601
829
  /** Where the parts of the value are. The default is `none`. */
602
830
  readonly parts?: Shape;
@@ -609,13 +837,20 @@ interface Kind {
609
837
  * itself.
610
838
  */
611
839
  readonly caps?: readonly CapsRule[];
612
- /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
840
+ /** The side of the verb `eval` of the kind. A kind of the run side causes effects. The default is `derive`. */
613
841
  readonly side?: Side;
614
842
  /**
615
- * The effects that a document of this kind can cause. It is a list of the kinds of the effects. The text
616
- * `"type"` means that the kind of the effect is the type of the document itself, as for a call.
843
+ * The effects that the verb `eval` of a document of this kind can cause. It is a list of the kinds of the effects.
844
+ * The text `"type"` means that the kind of the effect is the type of the document itself, as for a call. For a
845
+ * procedure entry, the list holds the latent effects of the procedure, and `checkLatent` compares them with its body
846
+ * (CAP.LATENT).
617
847
  */
618
848
  readonly effects?: "type" | readonly string[];
849
+ /**
850
+ * The value type of the result of the verb `eval`, when it is fixed (TYPE.SYNTH). A check of types gives it to each
851
+ * document of the kind, in the place of the type that the rule of the evaluator synthesizes.
852
+ */
853
+ readonly result?: ValueType;
619
854
  /** One sentence that tells what the kind is. */
620
855
  readonly summary?: string;
621
856
  }
@@ -637,6 +872,10 @@ type WorldEntry = Kind | Namespace | Alias;
637
872
  */
638
873
  interface World {
639
874
  readonly kinds: Readonly<Record<string, WorldEntry>>;
875
+ /**
876
+ * The default evaluator of each verb: the last rung of the ladder (LADDER.DEFAULT). It serves each verb, also
877
+ * `deref` and `step`. Without a default of `deref`, a step goes into the value of a document (VERB.LADDER).
878
+ */
640
879
  readonly defaults: Readonly<Record<string, string>>;
641
880
  readonly fallback?: Kind;
642
881
  }
@@ -780,7 +1019,8 @@ export declare function kindNamed(world: World, name: TypeRef): Kind | undefined
780
1019
  *
781
1020
  * The question visits the rungs in order: the own entry of the envelope, then its kind, then the default of the
782
1021
  * world. The type comes from the envelope, or else from the type that the position declares. The type is a
783
- * reference into the world. The ladder does not guess a type from the shape of a value.
1022
+ * reference into the world. The ladder does not guess a type from the shape of a value. Each verb has this ladder:
1023
+ * `eval`, `deref`, `step` and each verb of a language (VERB.LADDER).
784
1024
  *
785
1025
  * @param world - The kinds and the defaults.
786
1026
  * @param doc - The header of the document: an envelope, or `{}` for a bare value.
@@ -788,7 +1028,446 @@ export declare function kindNamed(world: World, name: TypeRef): Kind | undefined
788
1028
  * @param options - The type that the position declares.
789
1029
  * @returns The answer, with the record of each rung that the question visited.
790
1030
  */
791
- export declare function ask(world: World, doc: Header, verb: string, options?: AskOptions): Answer;
1031
+ export declare function ask(world: World, doc: Header, verb: string, options?: AskOptions): Answer;
1032
+ //#endregion
1033
+ //#region src/parts.d.ts
1034
+ /** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
1035
+ interface PartSlot {
1036
+ /** The keys from the value of the document to the part. */
1037
+ readonly path: readonly Key[];
1038
+ /** The path as one text, with a dot between the keys, for example `bind.x`. A part of a list has its index. */
1039
+ readonly key: string;
1040
+ readonly item: Json;
1041
+ readonly of?: string;
1042
+ /** `true` when the position of the part declares an address: a reference there gives what its path reaches. */
1043
+ readonly address?: true;
1044
+ /** The value type that the shape declares for the part (`expect`). Only a check of types reads it. */
1045
+ readonly expect?: ValueType;
1046
+ }
1047
+ /** The value of a document, split into its parts, by the shape that its kind declares. */
1048
+ type Split = {
1049
+ readonly ok: true;
1050
+ /** The parts, in the order of the value. */
1051
+ readonly parts: readonly PartSlot[];
1052
+ /** The value without the parts: a field that holds a part is not in it, and a list of parts gives `null`. */
1053
+ readonly data: Json;
1054
+ /**
1055
+ * This function gives the value with a handle in the place of each part.
1056
+ *
1057
+ * @param handles - One handle for each part, in the order of `parts`.
1058
+ * @returns The value with the handles.
1059
+ */
1060
+ fill<P>(handles: readonly P[]): unknown;
1061
+ } | {
1062
+ readonly ok: false;
1063
+ readonly reason: string;
1064
+ readonly at: readonly Key[];
1065
+ };
1066
+ /**
1067
+ * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
1068
+ * the static kit use the same split, thus each one sees the same parts.
1069
+ *
1070
+ * @param shape - The shape of the value. The default is data.
1071
+ * @param value - The value of the document.
1072
+ * @returns The parts and a way to fill their places, or the reason why the value does not have the shape.
1073
+ */
1074
+ export declare function splitParts(shape: Shape | undefined, value: Json): Split;
1075
+ /**
1076
+ * The kind and the parts of one document: what `partsOf` gives. `ok` is `false` only when the value is not a
1077
+ * document: it has no envelope, and its position declares no type. A value without the shape of its kind gives a
1078
+ * failed `split`.
1079
+ */
1080
+ type DocParts = {
1081
+ readonly ok: true;
1082
+ /** The document. A bare value gets the type that its position declares. */
1083
+ readonly doc: Envelope;
1084
+ /** `true` when the type came from the position and not from an envelope. */
1085
+ readonly declared: boolean;
1086
+ /** The kind, or `undefined` when the world has no kind for the type. Then the value is data. */
1087
+ readonly kind: Kind | undefined;
1088
+ /** The keys of the kind after each alias, or `undefined` without a kind. */
1089
+ readonly typePath: readonly Key[] | undefined;
1090
+ /**
1091
+ * The split of the value by the shape of the kind. The reason of a failed split is the reason of the `#VALUE!`
1092
+ * of an evaluation: it names the kind. Its `at` gives the keys from the value to the problem.
1093
+ */
1094
+ readonly split: Split;
1095
+ } | {
1096
+ readonly ok: false;
1097
+ readonly code: "#PART?";
1098
+ readonly reason: string;
1099
+ };
1100
+ /**
1101
+ * This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
1102
+ * the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
1103
+ * reference interpreter and the static kit read each document with this function. Thus they see the same parts.
1104
+ *
1105
+ * @param world - The world of the kinds.
1106
+ * @param value - The document, or a bare value.
1107
+ * @param declaredType - The type that the position of a bare value declares.
1108
+ * @returns The document, its kind and its parts, or the reason why the value is not a document.
1109
+ */
1110
+ export declare function partsOf(world: World, value: unknown, declaredType?: string): DocParts;
1111
+ /**
1112
+ * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
1113
+ * each key.
1114
+ *
1115
+ * @param path - The path of the part.
1116
+ * @param pattern - The pattern.
1117
+ * @returns `true` when the path matches.
1118
+ */
1119
+ export declare function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean;
1120
+ //#endregion
1121
+ //#region src/static.d.ts
1122
+ /** One document that a walk visits. */
1123
+ interface DocVisit {
1124
+ /** The keys from the root document to this document, through the parts. It is the place of an error. */
1125
+ readonly place: readonly Key[];
1126
+ /** The keys from the root JSON value to this document. A change at this path changes this document. */
1127
+ readonly at: readonly Key[];
1128
+ /** The visit of the document that holds this document as a part. The root has none. */
1129
+ readonly parent?: DocVisit | undefined;
1130
+ /** The keys from the value of the parent to this document: the path of the part. The root has none. */
1131
+ readonly slot: readonly Key[];
1132
+ /** The document. A bare value has the type that its position declares. */
1133
+ readonly doc: Envelope;
1134
+ /** `true` when the type came from the position and not from an envelope. */
1135
+ readonly declared: boolean;
1136
+ /** The kind of the document, when the world has it. */
1137
+ readonly kind?: Kind | undefined;
1138
+ /** The keys of the kind after each alias. */
1139
+ readonly typePath?: readonly Key[] | undefined;
1140
+ /** The number of documents around this document. The root has 0. */
1141
+ readonly depth: number;
1142
+ /** The names that the kinds around this document bind for it. */
1143
+ readonly names: ReadonlySet<string>;
1144
+ /** The names that a sequence around this document binds only for the parts after it. */
1145
+ readonly later: ReadonlySet<string>;
1146
+ /** `true` when the position of the document declares an address: a reference there is not a read of a value. */
1147
+ readonly address?: true | undefined;
1148
+ /**
1149
+ * The capabilities of the document: the capabilities of the walk, narrowed by the capability rules of the kinds
1150
+ * around it (`Kind.caps`). A walk without capabilities gives none here.
1151
+ */
1152
+ readonly caps?: readonly Cap[] | undefined;
1153
+ }
1154
+ /** A position that a walk cannot read as a document. */
1155
+ interface WalkProblem {
1156
+ /** The keys from the root document to the document with the problem. */
1157
+ readonly place: readonly Key[];
1158
+ /** The keys from the root JSON value to the value with the problem. */
1159
+ readonly at: readonly Key[];
1160
+ readonly code: "#PART?" | "#VALUE!";
1161
+ readonly reason: string;
1162
+ }
1163
+ /** The options of a walk. */
1164
+ interface WalkOptions {
1165
+ /** The type of a bare root value. */
1166
+ readonly declaredType?: string;
1167
+ /** The names that the host binds at the root. */
1168
+ readonly names?: readonly string[];
1169
+ /** The capabilities at the root. With them, each visit gets the capabilities of its document. */
1170
+ readonly caps?: readonly Cap[];
1171
+ /**
1172
+ * This function gets each position that is not a document.
1173
+ *
1174
+ * @param problem - The position and the reason.
1175
+ */
1176
+ readonly problem?: (problem: WalkProblem) => void;
1177
+ }
1178
+ /**
1179
+ * This function visits each document of a document: the root and each part at each depth, by the contracts of the
1180
+ * kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
1181
+ * narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
1182
+ * depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
1183
+ * document. A visit makes the keys of its place and of its path only when a reader asks for them.
1184
+ *
1185
+ * @param world - The world of the kinds.
1186
+ * @param doc - The document, as JSON.
1187
+ * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
1188
+ * @param options - The type of a bare root value, the names, the capabilities and a function for the problems.
1189
+ */
1190
+ export declare function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options?: WalkOptions): void;
1191
+ /** One reference of a document. */
1192
+ interface RefUse {
1193
+ /** The visit of the reference document: its parent, its depth and the names that it sees. */
1194
+ readonly visit: DocVisit;
1195
+ /** The place of the reference document, through the parts. */
1196
+ readonly place: readonly Key[];
1197
+ /** The keys from the root JSON value to the reference document. */
1198
+ readonly at: readonly Key[];
1199
+ /** The path of the reference: its root and its steps. */
1200
+ readonly path: readonly Json[];
1201
+ readonly root: string;
1202
+ /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
1203
+ readonly free: boolean;
1204
+ /** `true` when the reference is an address: its position declares it. An address does not read a value. */
1205
+ readonly address: boolean;
1206
+ }
1207
+ /**
1208
+ * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
1209
+ * reference to a name that a kind around it binds is not free. The others are what the document reads from
1210
+ * outside: its dependencies. When the kind `ref` has parts, the walk also finds the references in its step documents.
1211
+ *
1212
+ * @param world - The world of the kinds.
1213
+ * @param doc - The document, as JSON.
1214
+ * @param options - The type of a bare root value. The names of the host do not change the result.
1215
+ * @returns The references, in the order of the document.
1216
+ */
1217
+ export declare function refsOf(world: World, doc: unknown, options?: WalkOptions): readonly RefUse[];
1218
+ /**
1219
+ * This function changes the free references of a document. The document is not changed: the function gives a new
1220
+ * document that shares each part without a change.
1221
+ *
1222
+ * @param world - The world of the kinds.
1223
+ * @param doc - The document, as JSON.
1224
+ * @param change - The function that gives the new document of a reference, or `undefined` to keep it.
1225
+ * @param options - The type of a bare root value, and the names that the host binds at the root.
1226
+ * @returns The new document.
1227
+ */
1228
+ export declare function mapRefs(world: World, doc: unknown, change: (use: RefUse) => unknown, options?: WalkOptions): unknown;
1229
+ /** A problem that a check finds before a document runs. */
1230
+ interface Issue {
1231
+ readonly code: ErrorCode;
1232
+ /** The keys from the root document to the document with the problem. */
1233
+ readonly place: readonly Key[];
1234
+ readonly reason: string;
1235
+ /** The keys from the root JSON value to the value with the problem. */
1236
+ readonly at?: readonly Key[];
1237
+ /** The type that the position needs, for a type issue (`#TYPE!`). */
1238
+ readonly expected?: ValueType;
1239
+ /** The type that the check found, for a type issue (`#TYPE!`). */
1240
+ readonly found?: ValueType;
1241
+ }
1242
+ /** The options of a check. */
1243
+ interface CheckOptions {
1244
+ /** The type of a bare root value. */
1245
+ readonly declaredType?: string;
1246
+ /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
1247
+ readonly names?: readonly string[] | "any";
1248
+ /**
1249
+ * The capabilities at the root. Without them, the check does not check the effects. The check narrows them for
1250
+ * each part by the capability rules of the kinds, as a run does.
1251
+ */
1252
+ readonly caps?: readonly Cap[];
1253
+ /**
1254
+ * The verb that goes up the ladder at each document, as in `prepare`. The default is `eval`. `#NOEVAL` and the hook
1255
+ * `known` follow this verb. The contract declares the effects and the value types of `eval` only, thus only `eval`
1256
+ * checks them (VERB.CHECK). The type rule of an evaluator serves each verb.
1257
+ */
1258
+ readonly verb?: string;
1259
+ /**
1260
+ * With `true`, the check also checks the value types (TYPE.CHECK). It reads the type rules of the evaluators, the
1261
+ * signatures of the operations and the value types of the contracts. A type issue has the code `#TYPE!`. The
1262
+ * default is `false`, thus a host opts in.
1263
+ */
1264
+ readonly types?: boolean;
1265
+ /** The type that the root document must have, for the check of the value types. */
1266
+ readonly expect?: ValueType;
1267
+ /**
1268
+ * With `true`, the check also finds the problems of a run (RUN.CAN-WAIT). A runner under a parent without a runner
1269
+ * gives `#CALC!` when an effect of its runners can reach the host. The parent cannot pass that wait through.
1270
+ * A runner without such an effect does not wait, and the run drives it (RUN.DRIVE-NESTED). A kind that declares
1271
+ * effects and has no runner gives `#CALC!` too, because in a run only a runner can wait for the host. The default is
1272
+ * `false`.
1273
+ */
1274
+ readonly run?: boolean;
1275
+ /**
1276
+ * The value types of the roots and of the names of the host, for the check of the value types (TYPE.ROOTS). A
1277
+ * reference then gets the type that its path reaches. Only a check with `types: true` reads them.
1278
+ */
1279
+ readonly rootTypes?: RootTypes;
1280
+ }
1281
+ /** The result of `typeCheck`. */
1282
+ interface Typing {
1283
+ /** The type of the root document. It is `unknown` when the root has an issue. */
1284
+ readonly type: ValueType;
1285
+ /** Each issue of the check. The type issues come after the other issues. */
1286
+ readonly issues: readonly Issue[];
1287
+ /** The type of each document, in the order of the document. */
1288
+ readonly places: readonly Typed[];
1289
+ }
1290
+ /**
1291
+ * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
1292
+ * that an evaluation finds when it reaches them:
1293
+ *
1294
+ * - `#KIND?`: a kind that the world does not have.
1295
+ * - `#NOEVAL`: no evaluator.
1296
+ * - `#VALUE!`: a value without the shape of its kind.
1297
+ * - `#PART?`: a value without a type.
1298
+ * - `#DEPTH!`: too much nesting.
1299
+ * - `#REF!` and `#STEP?`: a bad path.
1300
+ * - `#NAME?`: a name that nothing binds. With the hook `known` of the machine, also a name that the language does not
1301
+ * have, for example an operation.
1302
+ * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
1303
+ * The hook `permits` of the machine decides, as in a run (CAP.PERMITS).
1304
+ * - `#CALC!`: with the option `run`, a runner under a parent without a runner, when an effect of its runners can reach
1305
+ * the host. Also a kind that declares effects and has no runner (RUN.CAN-WAIT). The issue has the place and the
1306
+ * reason of the run.
1307
+ * - `#TYPE!`: with the option `types`, a part whose type does not fit the type that its position needs (TYPE.CHECK).
1308
+ * A run does not always fail there, thus a type issue is a static finding, not an error of a run.
1309
+ *
1310
+ * The check asks the ladder for the verb of the options, `eval` by default (VERB.CHECK). The shapes, the paths and the
1311
+ * names follow the contracts, thus they are the same for each verb. Only `eval` checks the declared effects.
1312
+ *
1313
+ * @param machine - The world and the code of the evaluators.
1314
+ * @param doc - The document, as JSON.
1315
+ * @param options - The type of a bare root value, the names of the host, the capabilities, the verb, the types and the run.
1316
+ * @returns The problems, in the order of the document. The type issues come after the other issues.
1317
+ */
1318
+ export declare function check(machine: Machine, doc: unknown, options?: CheckOptions): readonly Issue[];
1319
+ /**
1320
+ * This function checks a document, and it also checks the value types (TYPE.CHECK, D25). It finds each issue of
1321
+ * `check`. Then it synthesizes the type of each document from the types of its parts. It also checks each part
1322
+ * against the type that its position needs. The type rule of the parent, the signature of an operation or the shape
1323
+ * of the contract gives that type. A part with an issue gets the type `unknown`, thus one
1324
+ * problem does not give a chain of issues.
1325
+ *
1326
+ * A type issue has the code `#TYPE!`, the type that the position needs (`expected`) and the type that the check found
1327
+ * (`found`). It is a static finding: the evaluation of the document does not change.
1328
+ *
1329
+ * The option `rootTypes` gives the types of the roots and of the names of the host (TYPE.ROOTS). A reference then gets
1330
+ * the type that its path reaches, and a field that a closed record does not have is a type issue (TYPE.CLOSED).
1331
+ *
1332
+ * @param machine - The world and the code of the evaluators, with their type rules.
1333
+ * @param doc - The document, as JSON.
1334
+ * @param options - The options of `check`, the type that the root must have and the types of the roots.
1335
+ * @returns The type of the root, each issue, and the type of each document.
1336
+ */
1337
+ export declare function typeCheck(machine: Machine, doc: unknown, options?: CheckOptions): Typing;
1338
+ //#endregion
1339
+ //#region src/typing.d.ts
1340
+ /** What a type rule gets for one document. */
1341
+ interface TypeInput {
1342
+ /** The keys of the kind of the document, after each alias. */
1343
+ readonly typePath: readonly Key[];
1344
+ /** The document. A bare value has the type that its position declares. */
1345
+ readonly doc: Envelope;
1346
+ /** The type that the position of the document needs. It is `unknown` when the position needs no type. */
1347
+ readonly expected: ValueType;
1348
+ /** The paths of the parts in the value, in the order of the value. */
1349
+ readonly paths: readonly (readonly Key[])[];
1350
+ /** `true` when the position declares an address. A reference there gives a thing, not a value. */
1351
+ readonly address: boolean;
1352
+ readonly machine: Machine;
1353
+ /**
1354
+ * This function gives the type of a part that the check typed before. It gives `unknown` for a part that the check
1355
+ * did not type yet, and for a part with an issue.
1356
+ *
1357
+ * @param path - The path of the part in the value.
1358
+ * @returns The type of the part.
1359
+ */
1360
+ typeOf(path: readonly Key[]): ValueType;
1361
+ /**
1362
+ * This function gives the type of a name: the type that a kind around the document binds. Without such a kind, it
1363
+ * gives the type from the option `rootTypes` of the host.
1364
+ *
1365
+ * @param name - The name.
1366
+ * @returns The type, or `undefined` when neither a kind around the document nor the host gives the name a type.
1367
+ */
1368
+ nameType(name: string): ValueType | undefined;
1369
+ /**
1370
+ * This function gives the type of a root of the context at the document (TYPE.ROOTS). The host gives the types of
1371
+ * `self`, `world` and `event` in the option `rootTypes`. A rule can give other types to its parts. The root `caps`
1372
+ * always has the type `CAPS_TYPE`. A rule reads the type of a name with `nameType`, thus the root `names` gives
1373
+ * `unknown`.
1374
+ *
1375
+ * @param root - The root.
1376
+ * @returns The type. It is `unknown` for a root without a type.
1377
+ */
1378
+ rootType(root: string): ValueType;
1379
+ /**
1380
+ * This function examines a value type of a contract with `typeIssues`, one time in a check. The first problem of a
1381
+ * type becomes an issue at the document. A term with a problem reads as `unknown`.
1382
+ *
1383
+ * @param type - The value type of the contract.
1384
+ * @param what - What the type is, for the reason, for example "the result of ops.add".
1385
+ * @returns The type.
1386
+ */
1387
+ contract(type: unknown, what: string): ValueType;
1388
+ }
1389
+ /** What a type rule tells for one part: the type that the part must have, and the types of the names of the part. */
1390
+ interface PartType {
1391
+ /** The type that the part must have. */
1392
+ readonly expect?: ValueType;
1393
+ /** What the part is, for the reason of an issue, for example "argument 2 of ops.add". */
1394
+ readonly what?: string;
1395
+ /** The types of the names that the scope rules of the kind bind for the part. Each other name of the rules gets `unknown`. */
1396
+ readonly names?: Readonly<Record<string, ValueType>>;
1397
+ /**
1398
+ * The types of the roots that the evaluator changes for the part, for example `self` for the attributes of a node.
1399
+ * Each other root keeps its type. The parts of an evaluator without a rule get `unknown` for each of these roots.
1400
+ */
1401
+ readonly roots?: Omit<RootTypes, "names">;
1402
+ }
1403
+ /**
1404
+ * The value types of the roots of a context, for a check of types (TYPE.ROOTS). The host gives them in the option
1405
+ * `rootTypes` of `check` and `typeCheck`. A root without a type has the type `unknown`. The root `caps` always has the
1406
+ * type `CAPS_TYPE`, because the kernel narrows it.
1407
+ *
1408
+ * The host keeps the types true: each root of the context holds a member of its type. A host thing, or a machine
1409
+ * with `adopt`, keeps each step true too. The context binds each name of `names`, thus the option `names` of `check`
1410
+ * lists it too.
1411
+ */
1412
+ interface RootTypes {
1413
+ /** The type of each name that the host binds. A name of the host without a type here has the type `unknown`. */
1414
+ readonly names?: Readonly<Record<string, ValueType>>;
1415
+ /** The type of `self`: the node or the position that the document is part of. */
1416
+ readonly self?: ValueType;
1417
+ /** The type of `world`, for example the schema of a store. The context then gives the world. */
1418
+ readonly world?: ValueType;
1419
+ /** The type of `event`: the event that started a run. */
1420
+ readonly event?: ValueType;
1421
+ }
1422
+ /**
1423
+ * The value type of the root `caps`: a list of capabilities. A capability is a text, or a list of keys. The kernel
1424
+ * narrows the capabilities for each part, thus the host does not give this type.
1425
+ */
1426
+ export declare const CAPS_TYPE: ValueType;
1427
+ /** A problem that a type rule finds. Its place is a part of the document, or the document itself. */
1428
+ interface TypeProblem {
1429
+ /** The path of the part in the value. Without it, the problem is at the document. */
1430
+ readonly path?: readonly Key[];
1431
+ readonly reason: string;
1432
+ readonly expected?: ValueType;
1433
+ readonly found?: ValueType;
1434
+ }
1435
+ /**
1436
+ * The type rule of an evaluator: what a check of types knows about the values that the evaluator gives. An evaluator
1437
+ * object holds its rule in its field `type`. Thus the rule follows the evaluator that the ladder gives a document
1438
+ * (TYPE.RULE).
1439
+ */
1440
+ interface TypeRule {
1441
+ /**
1442
+ * This function tells the type that a part must have, and the types of the names for the part. The check asks it
1443
+ * before it types the part. The parts that give the names of a rule `keysAt` come first.
1444
+ *
1445
+ * @param input - The document, the type that its position needs, and the types of the parts before.
1446
+ * @param path - The path of the part in the value.
1447
+ * @returns The type of the part and the types of its names.
1448
+ */
1449
+ readonly part?: (input: TypeInput, path: readonly Key[]) => PartType;
1450
+ /**
1451
+ * This function synthesizes the type of the document from the types of its parts. It must be sound: each value that
1452
+ * the evaluator gives is a member of the type.
1453
+ *
1454
+ * @param input - The document, the type that its position needs, and the types of its parts.
1455
+ * @param report - The function that gets each problem that the rule finds.
1456
+ * @returns The type of the document.
1457
+ */
1458
+ readonly synth: (input: TypeInput, report: (problem: TypeProblem) => void) => ValueType;
1459
+ }
1460
+ /** The type of one document of a check of types. */
1461
+ interface Typed {
1462
+ /** The keys from the root document to the document. */
1463
+ readonly place: readonly Key[];
1464
+ /** The keys from the root JSON value to the document. */
1465
+ readonly at: readonly Key[];
1466
+ /** The type that the check synthesized. A document with an issue has the type `unknown`. */
1467
+ readonly type: ValueType;
1468
+ /** The type that the position of the document needs, when it needs one. */
1469
+ readonly expected?: ValueType;
1470
+ }
792
1471
  //#endregion
793
1472
  //#region src/evaluate.d.ts
794
1473
  /**
@@ -882,6 +1561,33 @@ interface Effect {
882
1561
  */
883
1562
  readonly outcome?: Result;
884
1563
  }
1564
+ /**
1565
+ * One read of an evaluation: a path that code resolved, and what the path reached (READS.RECORD, D26). A schedule
1566
+ * keeps the list of the reads of an evaluation. `verifyReads` resolves each free read again in a new context, and it
1567
+ * tells if the old result stays valid.
1568
+ */
1569
+ interface Read {
1570
+ /** The path that the code resolved: its root, and its steps with the value of each step document. */
1571
+ readonly path: readonly unknown[];
1572
+ /**
1573
+ * What the path reached: the thing, or the error of the resolution. A host thing stays a thing. An exception of the
1574
+ * host gives its error value.
1575
+ */
1576
+ readonly reached: Result;
1577
+ /**
1578
+ * `true` when the read reads the context of the evaluation (READS.FREE). A read of a name that a kind binds, for
1579
+ * example a name of `let`, is not free. A read of a `self` that a kind sets is not free either, for example a node
1580
+ * of a tree. A path without a root is not free. `verifyReads` resolves only the free reads again.
1581
+ */
1582
+ readonly free: boolean;
1583
+ /**
1584
+ * `true` when the kernel adds the read, because a value keeps a root of the context for later (READS.KEPT). Such a
1585
+ * read has the whole root as its path.
1586
+ */
1587
+ readonly kept?: true;
1588
+ /** The hops of the resolution, only when the code asked for them. `verifyReads` then compares each hop too. */
1589
+ readonly hops?: readonly Hop[];
1590
+ }
885
1591
  /**
886
1592
  * The host side of a run: it does one effect, and gives its result. A throw or a rejection is an error value, and a
887
1593
  * `Failure` gives its own error value. In an evaluation, this function is a mock: it answers at once, and a promise
@@ -932,7 +1638,7 @@ interface Runtime {
932
1638
  * This function causes an effect from an evaluator. In a run, an evaluator cannot cause an effect: the host does
933
1639
  * each effect, thus only a runner can wait for it.
934
1640
  *
935
- * @param ctx - The context of the document.
1641
+ * @param ctx - The context of the document. It gives only the capabilities that the document has (CAP.NARROW-CODE).
936
1642
  * @param kind - The kind of the effect.
937
1643
  * @param payload - The data of the effect.
938
1644
  * @param place - The place of the document.
@@ -943,7 +1649,7 @@ interface Runtime {
943
1649
  * This function causes an effect from a runner. In a run, the host does it, and the steps wait when the host
944
1650
  * waits.
945
1651
  *
946
- * @param ctx - The context of the document.
1652
+ * @param ctx - The context of the document. It gives only the capabilities that the document has (CAP.NARROW-CODE).
947
1653
  * @param kind - The kind of the effect.
948
1654
  * @param payload - The data of the effect.
949
1655
  * @param place - The place of the document.
@@ -958,6 +1664,12 @@ interface Runtime {
958
1664
  * @returns The steps that give each result, in the order of the list.
959
1665
  */
960
1666
  all(list: readonly (() => Steps)[], options?: AllOptions): Generator<Promise<unknown>, readonly Result[], unknown>;
1667
+ /**
1668
+ * This optional function tells the runtime that a value keeps the context for later, for example a closure of
1669
+ * `fn`. A later use of the value reads that context, and no evaluation records these reads. Thus the list of reads
1670
+ * gets a read of each root of the context (READS.KEPT).
1671
+ */
1672
+ keepsContext?(): void;
961
1673
  }
962
1674
  /**
963
1675
  * The options of a drive of parts at the same time.
@@ -970,9 +1682,16 @@ interface AllOptions {
970
1682
  readonly concurrency?: number;
971
1683
  readonly failFast?: boolean;
972
1684
  }
973
- /** Compiled code: the evaluation of a document in a context. */
1685
+ /**
1686
+ * Compiled code: the evaluation of a document in a context. The code gives each part a context that it makes from
1687
+ * its own context with a spread. The part then keeps only the capabilities of the document (CAP.NARROW-CODE). A
1688
+ * context that the code makes without a spread gives the part no capabilities.
1689
+ */
974
1690
  type Code = (ctx: Context, rt: Runtime) => Result;
975
- /** Compiled code that can wait: the run of a document in a context. */
1691
+ /**
1692
+ * Compiled code that can wait: the run of a document in a context. Its parts keep only the capabilities of the
1693
+ * document, as for `Code`.
1694
+ */
976
1695
  type RunCode = (ctx: Context, rt: Runtime) => Steps;
977
1696
  /** A compiled part: its place in its parent, its binding name, and its code. It has no field with its value. */
978
1697
  interface CompiledPart {
@@ -1050,6 +1769,8 @@ interface EvalInput {
1050
1769
  readonly context: Context;
1051
1770
  /** The keys from the root document to this document. */
1052
1771
  readonly place: readonly Key[];
1772
+ /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
1773
+ readonly machine?: Machine;
1053
1774
  /** `true` when the position of the document declares an address. */
1054
1775
  readonly address?: boolean;
1055
1776
  /**
@@ -1105,6 +1826,8 @@ interface RunInput {
1105
1826
  readonly parts: readonly RunPart[];
1106
1827
  readonly context: Context;
1107
1828
  readonly place: readonly Key[];
1829
+ /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
1830
+ readonly machine?: Machine;
1108
1831
  resolve(path: readonly unknown[], options?: ResolveOptions): Resolution;
1109
1832
  /**
1110
1833
  * This function causes an effect. In a run, the host does the effect, and the steps wait when the host waits. In
@@ -1144,6 +1867,11 @@ interface CompiledEvaluator {
1144
1867
  * @returns The code that evaluates the document.
1145
1868
  */
1146
1869
  readonly compile: (input: CompileInput) => Code;
1870
+ /**
1871
+ * The type rule of the evaluator: the value types that a check of types gives its documents and their parts
1872
+ * (TYPE.RULE). Only a check reads it. An evaluator without a rule gives `unknown`.
1873
+ */
1874
+ readonly type?: TypeRule;
1147
1875
  }
1148
1876
  /** An evaluator: a function of its input, or a compiler. */
1149
1877
  type Evaluator = EvalFn | CompiledEvaluator;
@@ -1168,8 +1896,11 @@ type Runner = RunFn | CompiledRunner;
1168
1896
  * A machine: a world of kinds, and the code of each evaluator name, of each `deref` and of each walker.
1169
1897
  *
1170
1898
  * - `maxDepth`: the deepest nesting of documents. The default is 1000.
1171
- * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities.
1899
+ * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities. A run,
1900
+ * `check` and `effectsOf` ask it (CAP.PERMITS). In a check, its context has only the capabilities and the world.
1172
1901
  * - `known`: the names that the evaluators know, for `check`. Without it, `check` does not check such names.
1902
+ * - `domains`: the value domains of the language, by the name of their base type (D22).
1903
+ * - `facts`: the static facts of the names that a fallback kind covers, for `factsOf` (D24).
1173
1904
  */
1174
1905
  interface Machine extends Navigator {
1175
1906
  readonly evaluators: Readonly<Record<string, Evaluator>>;
@@ -1183,10 +1914,26 @@ interface Machine extends Navigator {
1183
1914
  * `check` asks it for each document with an evaluator. The function must be pure.
1184
1915
  *
1185
1916
  * @param path - The keys of the kind of the document, after each alias.
1186
- * @param evaluator - The name of the evaluator that the ladder gives the document.
1917
+ * @param evaluator - The name of the evaluator that the ladder of the verb of the check gives the document.
1187
1918
  * @returns `true` when the evaluator knows the name, or else the reason of the `#NAME?` that a run gives.
1188
1919
  */
1189
1920
  readonly known?: (path: readonly Key[], evaluator: string) => true | string;
1921
+ /**
1922
+ * The value domains of the language, by the name of their base type, for example a color or a unit of length. A
1923
+ * check reads them through `fits` and `member`. A domain of the kernel that the table does not name comes from
1924
+ * `STD_DOMAINS`.
1925
+ */
1926
+ readonly domains?: Readonly<Record<string, Domain>>;
1927
+ /**
1928
+ * This function gives the static facts of the code of a name, for `factsOf` (D24). An example is the operation
1929
+ * `["ops", "now"]` of a formula language: a fallback kind names it, and only the language knows that it is volatile.
1930
+ * Each field of the answer wins over the same field of the contract of the kind. The function must be pure.
1931
+ *
1932
+ * @param path - The keys of the kind of the document, after each alias.
1933
+ * @param code - The name of the evaluator of the document, or of the walker of a step document.
1934
+ * @returns The facts, or `undefined` for the facts of the contract.
1935
+ */
1936
+ readonly facts?: (path: readonly Key[], code: string) => KindFacts | undefined;
1190
1937
  }
1191
1938
  /** One evaluation in a trace. The children are the evaluations of its parts, in the order that they started. */
1192
1939
  interface TraceNode {
@@ -1197,7 +1944,7 @@ interface TraceNode {
1197
1944
  readonly doc: Envelope;
1198
1945
  /** `true` when the type came from the container and not from an envelope. */
1199
1946
  readonly declared: boolean;
1200
- /** The answer of the ladder to the verb `eval`. */
1947
+ /** The answer of the ladder to the verb of the plan, `eval` by default. */
1201
1948
  readonly answer: Answer;
1202
1949
  readonly side: Side;
1203
1950
  /** The names that the document could read when its evaluation started. */
@@ -1239,8 +1986,18 @@ interface RunOptions {
1239
1986
  readonly perform?: Perform;
1240
1987
  /** The type of a bare root value. */
1241
1988
  readonly declaredType?: string;
1989
+ /**
1990
+ * The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). A plan keeps the verb of its
1991
+ * `prepare`, thus `plan.run` does not read this option.
1992
+ */
1993
+ readonly verb?: string;
1242
1994
  /** A signal of the host. When it aborts, the run stops with `#ABORT`. */
1243
1995
  readonly signal?: StopSignal;
1996
+ /**
1997
+ * A list that gets each read, in the order of the resolutions (READS.RECORD). Under `all`, the order of the host
1998
+ * decides the order of the reads of the items.
1999
+ */
2000
+ readonly reads?: Read[];
1244
2001
  }
1245
2002
  /** The options of an evaluation of a plan. */
1246
2003
  interface EvalOptions {
@@ -1251,13 +2008,22 @@ interface EvalOptions {
1251
2008
  * Without it, an effect gives its payload (RUN.EVAL).
1252
2009
  */
1253
2010
  readonly perform?: Perform;
2011
+ /**
2012
+ * A list that gets each read, in the order of the resolutions (READS.RECORD). Without it, the plan records no read,
2013
+ * and each resolution costs one more test.
2014
+ */
2015
+ readonly reads?: Read[];
1254
2016
  }
1255
2017
  /** The options of `evaluate`. */
1256
2018
  interface EvaluateOptions {
1257
2019
  /** The type of a bare root value. */
1258
2020
  readonly declaredType?: string;
2021
+ /** The verb that goes up the ladder at each document, for example `format`. The default is `eval` (VERB.PREPARE). */
2022
+ readonly verb?: string;
1259
2023
  /** The mock of the host (RUN.MOCK). Without it, an effect gives its payload (RUN.EVAL). */
1260
2024
  readonly perform?: Perform;
2025
+ /** A list that gets each read, in the order of the resolutions (READS.RECORD). */
2026
+ readonly reads?: Read[];
1261
2027
  }
1262
2028
  /** The options of a compilation. */
1263
2029
  interface PrepareOptions {
@@ -1265,6 +2031,11 @@ interface PrepareOptions {
1265
2031
  readonly declaredType?: string;
1266
2032
  /** `true`: each evaluation records a trace. The default is `false`. */
1267
2033
  readonly trace?: boolean;
2034
+ /**
2035
+ * The verb that goes up the ladder at each document, for example `format`. Each part evaluates with the same verb.
2036
+ * The default is `eval` (VERB.PREPARE).
2037
+ */
2038
+ readonly verb?: string;
1268
2039
  }
1269
2040
  /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
1270
2041
  interface Plan {
@@ -1278,7 +2049,7 @@ interface Plan {
1278
2049
  * effect at once (RUN.MOCK).
1279
2050
  *
1280
2051
  * @param context - The names and the capabilities at the root.
1281
- * @param options - A list that gets the effects, and the mock of the host.
2052
+ * @param options - A list that gets the effects, the mock of the host and a list that gets the reads.
1282
2053
  * @returns The result.
1283
2054
  */
1284
2055
  evaluate(context?: Context, options?: EvalOptions): Result;
@@ -1286,7 +2057,7 @@ interface Plan {
1286
2057
  * This function runs the document: the host does each effect, and the run waits when the host waits.
1287
2058
  *
1288
2059
  * @param context - The names and the capabilities at the root.
1289
- * @param options - The host code that does the effects, and a signal to stop the run.
2060
+ * @param options - The host code that does the effects, a signal to stop the run and a list that gets the reads.
1290
2061
  * @returns The result, when the run ends.
1291
2062
  */
1292
2063
  run(context?: Context, options?: RunOptions): Promise<Result>;
@@ -1295,9 +2066,13 @@ interface Plan {
1295
2066
  * This function compiles a document into a plan. The ladder, the kinds and the parts are known after it. A plan
1296
2067
  * evaluates many times. A document that does not compile gives a plan that fails with the reason, when it evaluates.
1297
2068
  *
2069
+ * The verb of the options goes up the ladder at each document, and each part evaluates with the same verb. The
2070
+ * default verb is `eval`. A plan of another verb, for example `format`, evaluates, runs and traces as a plan of
2071
+ * `eval` does (VERB.PREPARE).
2072
+ *
1298
2073
  * @param machine - The world and the code of the evaluators.
1299
2074
  * @param doc - The document, as JSON.
1300
- * @param options - The type of a bare root value, and a trace.
2075
+ * @param options - The type of a bare root value, a trace and the verb.
1301
2076
  * @returns The plan.
1302
2077
  */
1303
2078
  export declare function prepare(machine: Machine, doc: unknown, options?: PrepareOptions): Plan;
@@ -1313,15 +2088,17 @@ export declare function planner(machine: Machine, options?: PrepareOptions): (do
1313
2088
  /**
1314
2089
  * This function evaluates a document, and records each evaluation in a trace.
1315
2090
  *
1316
- * The verb `eval` goes up the ladder for each document. The kind of the document tells where its parts are. The
1317
- * evaluator gets each part sealed: it can evaluate the part, and it cannot read its value. A failure gives an error
1318
- * value, and the function does not throw. An effect is recorded in its order, and the host does not do it. A mock
1319
- * can answer each effect at once (RUN.MOCK).
2091
+ * The verb of the options goes up the ladder for each document. The default verb is `eval`. The kind of the document
2092
+ * tells where its parts are. The evaluator gets each part sealed: it can evaluate the part, and it cannot read its
2093
+ * value.
2094
+ *
2095
+ * A failure gives an error value, and the function does not throw. An effect is recorded in its order, and the host
2096
+ * does not do it. A mock can answer each effect at once (RUN.MOCK).
1320
2097
  *
1321
2098
  * @param machine - The world and the code of the evaluators.
1322
2099
  * @param doc - The document, as JSON.
1323
2100
  * @param context - The names and the capabilities at the root.
1324
- * @param options - The type of a bare root value, or the options: that type and the mock of the host.
2101
+ * @param options - The type of a bare root value, or the options: that type, the mock of the host, the verb and a list for the reads.
1325
2102
  * @returns The result, the trace and the effects in their order.
1326
2103
  */
1327
2104
  export declare function evaluate(machine: Machine, doc: unknown, context?: Context, options?: string | EvaluateOptions): Run;
@@ -1333,7 +2110,7 @@ export declare function evaluate(machine: Machine, doc: unknown, context?: Conte
1333
2110
  * @param machine - The world, the evaluators and the runners.
1334
2111
  * @param doc - The document, as JSON.
1335
2112
  * @param context - The names and the capabilities at the root.
1336
- * @param options - The host code that does the effects, the type of a bare root value, and a signal.
2113
+ * @param options - The host code that does the effects, the type of a bare root value, a signal, the verb and a list for the reads.
1337
2114
  * @returns The result, the trace and the effects in their order, when the run ends.
1338
2115
  */
1339
2116
  export declare function run(machine: Machine, doc: unknown, context?: Context, options?: RunOptions): Promise<Run>;
@@ -1401,6 +2178,28 @@ export declare class MergeError extends Error {
1401
2178
  */
1402
2179
  constructor(conflicts: readonly MergeConflict[]);
1403
2180
  }
2181
+ /** What `extendDomain` adds to a domain: more parents, and the types of more steps. */
2182
+ interface DomainExtension {
2183
+ /** The names of the parents to add. A member of the domain then also passes the test of each new parent. */
2184
+ readonly under?: readonly string[];
2185
+ /** The types of the steps to add. A step with the key of an earlier step replaces its type. */
2186
+ readonly steps?: Readonly<Record<string, ValueType>>;
2187
+ }
2188
+ /**
2189
+ * This function makes a part of a merge that adds parents or steps to a domain of an earlier part (TYPE.PARENTS). An
2190
+ * example is a domain of another language. The part reads the domain from the merge before it (`prev`). It gives a
2191
+ * copy with the same test and summary, and it names `["domains", name]` in `replaces` (D17). A domain of the kernel
2192
+ * that the earlier parts do not name comes from `STD_DOMAINS`.
2193
+ *
2194
+ * A new parent adds its test to the domain (TYPE.MEMBER). Thus `fits` stays sound, but a value that fails the test of
2195
+ * the parent is no longer a member. The language that adds the parent keeps the signatures of the other language
2196
+ * true. A name without a domain gives an empty part, and `typeIssues` reports each use of that name.
2197
+ *
2198
+ * @param name - The name of the domain.
2199
+ * @param more - The parents and the steps to add.
2200
+ * @returns The part, as a function of the merge before it.
2201
+ */
2202
+ export declare function extendDomain(name: string, more: DomainExtension): (prev: Machine) => MachinePart;
1404
2203
  /**
1405
2204
  * This function merges worlds into one world, in the order of the parts. It does not change a part.
1406
2205
  *
@@ -1423,9 +2222,11 @@ export declare function mergeWorlds(...parts: readonly (WorldPart | ((prev: Worl
1423
2222
  *
1424
2223
  * - The worlds merge with the rules of `mergeWorlds`. The paths of their conflicts start with `"world"`.
1425
2224
  * - The tables `evaluators`, `runners`, `derefs` and `walkers` merge name by name. A function is equal only to itself.
2225
+ * - The table `domains` merges name by name. Two domains with the same test, parents and summary give one domain (D22).
1426
2226
  * - The evaluator and the runner of a name are its code. A replacement of the name replaces both.
1427
2227
  * - A runner hides the evaluator of its name. Thus one part must give both, or the merge gives a conflict.
1428
2228
  * - The hooks `known` compose in the order of the parts. A hook does not answer for a name that a later part replaces.
2229
+ * The hooks `facts` compose the same way, and the first answer that is not `undefined` wins.
1429
2230
  * - Each other field, for example `permits`, `adopt`, `roots`, `plain` or `maxDepth`, is one value. Two different
1430
2231
  * values are a conflict. An absent field has no value.
1431
2232
  *
@@ -1457,7 +2258,7 @@ export declare function restrictWorld(world: World, paths: readonly MergePath[])
1457
2258
  *
1458
2259
  * - A path that starts with `"world"` removes an entry of the world, with the rules of `restrictWorld`.
1459
2260
  * - `["evaluators", name]` or `["runners", name]` removes the code of the name: its evaluator and its runner.
1460
- * - `["derefs", name]` and `["walkers", name]` remove one entry of their tables.
2261
+ * - `["derefs", name]`, `["walkers", name]` and `["domains", name]` remove one entry of their tables.
1461
2262
  *
1462
2263
  * A path that names no entry changes nothing. The function does not change the machine. An own entry names an
1463
2264
  * evaluator directly, thus only a machine without the code of a name refuses each document that names it.
@@ -1504,92 +2305,6 @@ export declare function classify(shapes: readonly Shape$1[], value: Json): Class
1504
2305
  */
1505
2306
  export declare function tag(value: Json, kind: string): Envelope;
1506
2307
  //#endregion
1507
- //#region src/parts.d.ts
1508
- /** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
1509
- interface PartSlot {
1510
- /** The keys from the value of the document to the part. */
1511
- readonly path: readonly Key[];
1512
- /** The path as one text, with a dot between the keys, for example `bind.x`. A part of a list has its index. */
1513
- readonly key: string;
1514
- readonly item: Json;
1515
- readonly of?: string;
1516
- /** `true` when the position of the part declares an address: a reference there gives what its path reaches. */
1517
- readonly address?: true;
1518
- }
1519
- /** The value of a document, split into its parts, by the shape that its kind declares. */
1520
- type Split = {
1521
- readonly ok: true;
1522
- /** The parts, in the order of the value. */
1523
- readonly parts: readonly PartSlot[];
1524
- /** The value without the parts: a field that holds a part is not in it, and a list of parts gives `null`. */
1525
- readonly data: Json;
1526
- /**
1527
- * This function gives the value with a handle in the place of each part.
1528
- *
1529
- * @param handles - One handle for each part, in the order of `parts`.
1530
- * @returns The value with the handles.
1531
- */
1532
- fill<P>(handles: readonly P[]): unknown;
1533
- } | {
1534
- readonly ok: false;
1535
- readonly reason: string;
1536
- readonly at: readonly Key[];
1537
- };
1538
- /**
1539
- * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
1540
- * the static kit use the same split, thus each one sees the same parts.
1541
- *
1542
- * @param shape - The shape of the value. The default is data.
1543
- * @param value - The value of the document.
1544
- * @returns The parts and a way to fill their places, or the reason why the value does not have the shape.
1545
- */
1546
- export declare function splitParts(shape: Shape | undefined, value: Json): Split;
1547
- /**
1548
- * The kind and the parts of one document: what `partsOf` gives. `ok` is `false` only when the value is not a
1549
- * document: it has no envelope, and its position declares no type. A value without the shape of its kind gives a
1550
- * failed `split`.
1551
- */
1552
- type DocParts = {
1553
- readonly ok: true;
1554
- /** The document. A bare value gets the type that its position declares. */
1555
- readonly doc: Envelope;
1556
- /** `true` when the type came from the position and not from an envelope. */
1557
- readonly declared: boolean;
1558
- /** The kind, or `undefined` when the world has no kind for the type. Then the value is data. */
1559
- readonly kind: Kind | undefined;
1560
- /** The keys of the kind after each alias, or `undefined` without a kind. */
1561
- readonly typePath: readonly Key[] | undefined;
1562
- /**
1563
- * The split of the value by the shape of the kind. The reason of a failed split is the reason of the `#VALUE!`
1564
- * of an evaluation: it names the kind. Its `at` gives the keys from the value to the problem.
1565
- */
1566
- readonly split: Split;
1567
- } | {
1568
- readonly ok: false;
1569
- readonly code: "#PART?";
1570
- readonly reason: string;
1571
- };
1572
- /**
1573
- * This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
1574
- * the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
1575
- * reference interpreter and the static kit read each document with this function. Thus they see the same parts.
1576
- *
1577
- * @param world - The world of the kinds.
1578
- * @param value - The document, or a bare value.
1579
- * @param declaredType - The type that the position of a bare value declares.
1580
- * @returns The document, its kind and its parts, or the reason why the value is not a document.
1581
- */
1582
- export declare function partsOf(world: World, value: unknown, declaredType?: string): DocParts;
1583
- /**
1584
- * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
1585
- * each key.
1586
- *
1587
- * @param path - The path of the part.
1588
- * @param pattern - The pattern.
1589
- * @returns `true` when the path matches.
1590
- */
1591
- export declare function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean;
1592
- //#endregion
1593
2308
  //#region src/stdlib.d.ts
1594
2309
  /**
1595
2310
  * The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
@@ -1627,7 +2342,7 @@ export declare const STD_WALKERS: Readonly<Record<string, Walker>>;
1627
2342
  * order. In a run, an effect ends before the next step starts.
1628
2343
  */
1629
2344
  export declare const STD_RUNNERS: Readonly<Record<string, Runner>>;
1630
- /** The machine of the examples: the standard world, its evaluators, its runners and its walkers. */
2345
+ /** The machine of the examples: the standard world, its evaluators, its runners, its walkers and the domains of the kernel. */
1631
2346
  export declare const STD_MACHINE: Machine;
1632
2347
  /** The capabilities of the examples at the root: the two effects of the standard world. */
1633
2348
  export declare const STD_CAPS: readonly string[];
@@ -1733,155 +2448,144 @@ interface Construct {
1733
2448
  /** Six constructs that show the range of the context. */
1734
2449
  export declare const CONSTRUCTS: readonly Construct[];
1735
2450
  //#endregion
1736
- //#region src/static.d.ts
1737
- /** One document that a walk visits. */
1738
- interface DocVisit {
1739
- /** The keys from the root document to this document, through the parts. It is the place of an error. */
1740
- readonly place: readonly Key[];
1741
- /** The keys from the root JSON value to this document. A change at this path changes this document. */
1742
- readonly at: readonly Key[];
1743
- /** The visit of the document that holds this document as a part. The root has none. */
1744
- readonly parent?: DocVisit | undefined;
1745
- /** The keys from the value of the parent to this document: the path of the part. The root has none. */
1746
- readonly slot: readonly Key[];
1747
- /** The document. A bare value has the type that its position declares. */
1748
- readonly doc: Envelope;
1749
- /** `true` when the type came from the position and not from an envelope. */
1750
- readonly declared: boolean;
1751
- /** The kind of the document, when the world has it. */
1752
- readonly kind?: Kind | undefined;
1753
- /** The keys of the kind after each alias. */
1754
- readonly typePath?: readonly Key[] | undefined;
1755
- /** The number of documents around this document. The root has 0. */
1756
- readonly depth: number;
1757
- /** The names that the kinds around this document bind for it. */
1758
- readonly names: ReadonlySet<string>;
1759
- /** The names that a sequence around this document binds only for the parts after it. */
1760
- readonly later: ReadonlySet<string>;
1761
- /** `true` when the position of the document declares an address: a reference there is not a read of a value. */
1762
- readonly address?: true | undefined;
2451
+ //#region src/facts.d.ts
2452
+ /**
2453
+ * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
2454
+ * when it evaluates the reference. The static read covers each path that the plan resolves there (FACTS.SOUND).
2455
+ */
2456
+ interface StaticRead {
2457
+ /** The root of the path. */
2458
+ readonly root: Root;
2459
+ /** The keys after the root, up to the first step that is not a key. */
2460
+ readonly keys: readonly Key[];
1763
2461
  /**
1764
- * The capabilities of the document: the capabilities of the walk, narrowed by the capability rules of the kinds
1765
- * around it (`Kind.caps`). A walk without capabilities gives none here.
2462
+ * `true` when each step after the root is a key. Then the plan resolves this path and no other. A step document,
2463
+ * for example `nearest`, makes it `false`: the plan resolves a path that starts with the keys.
1766
2464
  */
1767
- readonly caps?: readonly Cap[] | undefined;
1768
- }
1769
- /** A position that a walk cannot read as a document. */
1770
- interface WalkProblem {
1771
- /** The keys from the root document to the document with the problem. */
2465
+ readonly exact: boolean;
2466
+ /** `true` when only a lazy part reaches the reference. An evaluation can then give a value without this read (FACTS.LAZY). */
2467
+ readonly lazy: boolean;
2468
+ /** `true` when the position of the reference declares an address. The read gives what the path reaches, not its value. */
2469
+ readonly address: boolean;
2470
+ /** The path of the reference: its root and its steps. */
2471
+ readonly path: readonly Json[];
2472
+ /** The keys from the root document to the reference document, through the parts. */
1772
2473
  readonly place: readonly Key[];
1773
- /** The keys from the root JSON value to the value with the problem. */
2474
+ /** The keys from the root JSON value to the reference document. */
1774
2475
  readonly at: readonly Key[];
1775
- readonly code: "#PART?" | "#VALUE!";
1776
- readonly reason: string;
1777
2476
  }
1778
- /** The options of a walk. */
1779
- interface WalkOptions {
2477
+ /** The static facts of one document (D24). They depend only on the document and the machine, not on a context. */
2478
+ interface DocFacts {
2479
+ /** The free references, in the order of the document (FACTS.READS). A reference to a name that a kind binds is not here. */
2480
+ readonly reads: readonly StaticRead[];
2481
+ /** `"run"` when one kind of the document is on the run side (FACTS.SIDE). */
2482
+ readonly side: Side;
2483
+ /** The kinds of the effects that the contracts declare, as texts with dots, each one time (FACTS.EFFECTS). */
2484
+ readonly effects: readonly string[];
2485
+ /**
2486
+ * `true` when each kind of the document declares `pure`, and the document has no effect and is not volatile. Then
2487
+ * its result depends only on what its reads give (FACTS.PURE).
2488
+ */
2489
+ readonly pure: boolean;
2490
+ /** `true` when the result can change while each read gives the same thing, for example with a clock (FACTS.VOLATILE). */
2491
+ readonly volatile: boolean;
2492
+ /** The number of documents in the document: a hint of the cost of an evaluation. */
2493
+ readonly size: number;
2494
+ }
2495
+ /** The options of `factsOf`. */
2496
+ interface FactsOptions {
1780
2497
  /** The type of a bare root value. */
1781
2498
  readonly declaredType?: string;
1782
- /** The names that the host binds at the root. */
1783
- readonly names?: readonly string[];
1784
- /** The capabilities at the root. With them, each visit gets the capabilities of its document. */
1785
- readonly caps?: readonly Cap[];
1786
2499
  /**
1787
- * This function gets each position that is not a document.
1788
- *
1789
- * @param problem - The position and the reason.
2500
+ * The verb whose evaluators the facts describe, as in `prepare`. The default is `eval`. The contract of a kind
2501
+ * describes the code of `eval` only. For another verb, only the hook `facts` describes the code (FACTS.VERB).
1790
2502
  */
1791
- readonly problem?: (problem: WalkProblem) => void;
1792
- }
1793
- /**
1794
- * This function visits each document of a document: the root and each part at each depth, by the contracts of the
1795
- * kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
1796
- * narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
1797
- * depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
1798
- * document. A visit makes the keys of its place and of its path only when a reader asks for them.
1799
- *
1800
- * @param world - The world of the kinds.
1801
- * @param doc - The document, as JSON.
1802
- * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
1803
- * @param options - The type of a bare root value, the names, the capabilities and a function for the problems.
1804
- */
1805
- export declare function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options?: WalkOptions): void;
1806
- /** One reference of a document. */
1807
- interface RefUse {
1808
- /** The visit of the reference document: its parent, its depth and the names that it sees. */
1809
- readonly visit: DocVisit;
1810
- /** The place of the reference document, through the parts. */
1811
- readonly place: readonly Key[];
1812
- /** The keys from the root JSON value to the reference document. */
1813
- readonly at: readonly Key[];
1814
- /** The path of the reference: its root and its steps. */
1815
- readonly path: readonly Json[];
1816
- readonly root: string;
1817
- /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
1818
- readonly free: boolean;
1819
- /** `true` when the reference is an address: its position declares it. An address does not read a value. */
1820
- readonly address: boolean;
1821
- }
1822
- /**
1823
- * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
1824
- * reference to a name that a kind around it binds is not free. The others are what the document reads from
1825
- * outside: its dependencies. When the kind `ref` has parts, the walk also finds the references in its step documents.
1826
- *
1827
- * @param world - The world of the kinds.
1828
- * @param doc - The document, as JSON.
1829
- * @param options - The type of a bare root value. The names of the host do not change the result.
1830
- * @returns The references, in the order of the document.
1831
- */
1832
- export declare function refsOf(world: World, doc: unknown, options?: WalkOptions): readonly RefUse[];
1833
- /**
1834
- * This function changes the free references of a document. The document is not changed: the function gives a new
1835
- * document that shares each part without a change.
1836
- *
1837
- * @param world - The world of the kinds.
1838
- * @param doc - The document, as JSON.
1839
- * @param change - The function that gives the new document of a reference, or `undefined` to keep it.
1840
- * @param options - The type of a bare root value, and the names that the host binds at the root.
1841
- * @returns The new document.
1842
- */
1843
- export declare function mapRefs(world: World, doc: unknown, change: (use: RefUse) => unknown, options?: WalkOptions): unknown;
1844
- /** A problem that a check finds before a document runs. */
1845
- interface Issue {
1846
- readonly code: ErrorCode;
1847
- /** The keys from the root document to the document with the problem. */
1848
- readonly place: readonly Key[];
1849
- readonly reason: string;
1850
- /** The keys from the root JSON value to the value with the problem. */
1851
- readonly at?: readonly Key[];
2503
+ readonly verb?: string;
2504
+ /**
2505
+ * This function tells if a read reaches a volatile value of the host, for example a function that reads a clock.
2506
+ * A read that it marks makes the document volatile (FACTS.VOLATILE).
2507
+ *
2508
+ * @param read - The read.
2509
+ * @returns `true` when the read reaches a volatile value.
2510
+ */
2511
+ readonly volatile?: (read: StaticRead) => boolean;
1852
2512
  }
1853
- /** The options of a check. */
1854
- interface CheckOptions {
2513
+ /**
2514
+ * This function gives the static facts of a document, for a schedule (R4 P2, D24). It walks the document one time,
2515
+ * by the contracts of its kinds:
2516
+ *
2517
+ * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
2518
+ * `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`.
2519
+ * - `side` and `effects`: from the contract of each kind.
2520
+ * - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
2521
+ * - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
2522
+ *
2523
+ * The hook `facts` of the machine answers for a name that a fallback kind covers, for example an operation. Its
2524
+ * answer wins over the contract of the kind. The contract of a kind does not describe the evaluator of an own
2525
+ * entry. Thus a document with an own entry for another evaluator is not pure, and each of its parts is lazy. The
2526
+ * hook can still answer for that evaluator.
2527
+ *
2528
+ * The option `verb` names the verb whose code the facts describe (FACTS.VERB). A contract describes the code of
2529
+ * `eval`, thus the rule of an own entry applies to each document for another verb. The side and the effects come
2530
+ * from the contracts for each verb.
2531
+ *
2532
+ * A read is one resolution of its path. A reference that the resolution reaches and follows is a part of that read
2533
+ * (DEREF.COLLAPSE), not a separate read. The facts depend only on the document and the machine. Thus a host computes
2534
+ * them again only after an edit of the document or of the machine.
2535
+ *
2536
+ * @param machine - The world, the code and the hook `facts`.
2537
+ * @param doc - The document, as JSON.
2538
+ * @param options - The type of a bare root value, the verb and the volatile reads of the host.
2539
+ * @returns The facts.
2540
+ */
2541
+ export declare function factsOf(machine: Machine, doc: unknown, options?: FactsOptions): DocFacts;
2542
+ //#endregion
2543
+ //#region src/effects.d.ts
2544
+ /** The options of `effectsOf`. */
2545
+ interface EffectsOptions {
1855
2546
  /** The type of a bare root value. */
1856
2547
  readonly declaredType?: string;
1857
- /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
1858
- readonly names?: readonly string[] | "any";
1859
2548
  /**
1860
- * The capabilities at the root. Without them, the check does not check the effects. The check narrows them for
1861
- * each part by the capability rules of the kinds, as a run does.
2549
+ * The capabilities at the root. With them, the result keeps only the effects that the rule of the machine permits at
2550
+ * their documents, as a run does (CAP.PERMITS). Without them, the root has each capability, and only the capability
2551
+ * rules of the kinds remove an effect.
1862
2552
  */
1863
2553
  readonly caps?: readonly Cap[];
1864
2554
  }
1865
2555
  /**
1866
- * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
1867
- * that an evaluation finds when it reaches them:
2556
+ * This function gives the effects of a document that can reach the host (CAP.EFFECTS-OF, R2 P3). The result is the
2557
+ * effects that the contract of each kind declares, without the effects that the capability rules around them remove.
2558
+ * A rule `mask` removes each effect of its parts, and a rule `only` removes each effect outside its list.
1868
2559
  *
1869
- * - `#KIND?`: a kind that the world does not have.
1870
- * - `#NOEVAL`: no evaluator.
1871
- * - `#VALUE!`: a value without the shape of its kind.
1872
- * - `#PART?`: a value without a type.
1873
- * - `#DEPTH!`: too much nesting.
1874
- * - `#REF!` and `#STEP?`: a bad path.
1875
- * - `#NAME?`: a name that nothing binds. With the hook `known` of the machine, also a name that the language does not
1876
- * have, for example an operation.
1877
- * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
2560
+ * Without capabilities in the options, the result is the least authority of the document. A host that grants these
2561
+ * kinds as capabilities grants each effect that a run of the document can give it. With capabilities, the result keeps
2562
+ * only the effects that the rule of the machine permits at their documents.
1878
2563
  *
1879
- * @param machine - The world and the code of the evaluators.
2564
+ * The result covers each effect that an evaluation or a run gives the host (CAP.EFFECTS-SOUND). A procedure value keeps
2565
+ * the capabilities of the document that made it, thus the effects of its body count at the body (CAP.LATENT). The
2566
+ * contract describes the code of its kind. The code of an own entry for another evaluator is outside the result.
2567
+ *
2568
+ * @param machine - The world and its contracts, and the hook `permits`.
1880
2569
  * @param doc - The document, as JSON.
1881
- * @param options - The type of a bare root value, the names of the host and the capabilities.
1882
- * @returns The problems, in the order of the document.
2570
+ * @param options - The type of a bare root value and the capabilities at the root.
2571
+ * @returns The kinds of the effects, as texts with dots, each one time, in the order of the document.
1883
2572
  */
1884
- export declare function check(machine: Machine, doc: unknown, options?: CheckOptions): readonly Issue[];
2573
+ export declare function effectsOf(machine: Machine, doc: unknown, options?: EffectsOptions): readonly string[];
2574
+ /**
2575
+ * This function compares the latent effects that a procedure declares with the body of the procedure (CAP.LATENT). A
2576
+ * procedure entry is a kind whose code evaluates the document of a procedure. Its field `effects` declares the latent
2577
+ * effects: the effects that a call of the procedure can cause. `check` tests each call against this declaration.
2578
+ *
2579
+ * The function gives a `#CAP!` for each effect of the body that can reach the host and that the declaration does not
2580
+ * permit. An effect that a kind in the body masks fails in the body, thus it is not a latent effect.
2581
+ *
2582
+ * @param machine - The world and its contracts.
2583
+ * @param declared - The latent effects that the procedure declares, for example the field `effects` of its kind.
2584
+ * @param body - The document of the procedure, as JSON.
2585
+ * @param options - The type of a bare root value.
2586
+ * @returns The issues, in the order of the body.
2587
+ */
2588
+ export declare function checkLatent(machine: Machine, declared: readonly Cap[], body: unknown, options?: Omit<EffectsOptions, "caps">): readonly Issue[];
1885
2589
  //#endregion
1886
2590
  //#region src/formula.d.ts
1887
2591
  /** An operation of a formula language: a function of the values of its arguments. */
@@ -1891,14 +2595,18 @@ type OpFn = (...args: never[]) => unknown;
1891
2595
  * example a default for an error.
1892
2596
  */
1893
2597
  type LazyOp = (args: readonly (() => Result)[]) => Result;
1894
- /** The code of an extension: it gives the value of the data of an extension document, in the context of the document. */
1895
- type ExtFn = (data: Json, context: Context) => Result;
2598
+ /**
2599
+ * The code of an extension: it gives the value of the data of an extension document, in the context of the document.
2600
+ * It also gets the domains of the machine, for the codecs of `ext.domain` (D40).
2601
+ */
2602
+ type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<string, Domain>>) => Result;
1896
2603
  /**
1897
2604
  * The rules of one formula language: its operations, and the rules that differ between languages.
1898
2605
  *
1899
2606
  * - `ops`: the operations of the namespace `ops`, by their name (the keys after `ops`, with dots between them).
1900
2607
  * - `lazy`: the operations that evaluate their arguments themselves.
1901
- * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined` and `ext.number`.
2608
+ * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined`, `ext.number` and
2609
+ * `ext.domain`.
1902
2610
  * - `truthy`: the truth of a value for `if`, `and` and `or`. `undefined` is an error `#VALUE!`. The default
1903
2611
  * accepts only `true` and `false`.
1904
2612
  * - `otherwise`: the value of an `if` without `else`. The default is `null`. A profile with this key gives its value,
@@ -1909,6 +2617,14 @@ type ExtFn = (data: Json, context: Context) => Result;
1909
2617
  * - `check`: a check of the value of an operation, for example "a number must be finite".
1910
2618
  * - `combine`: the error of two or more failed parts of an operation, a `record` or a `list`. With it, each part
1911
2619
  * evaluates, and one failed part gives its own error. Without it, the first error stops the evaluation.
2620
+ * - `pure`: the pure operations, for `factsOf` (D24). `true` names each operation that is not volatile. The default
2621
+ * names no operation.
2622
+ * - `volatile`: the operations whose results can change while their arguments stay the same, for example a clock.
2623
+ * - `sigs`: the signatures of the operations, by their name, for a check of types (TYPE.SIGNATURE). A list gives
2624
+ * overloads. An operation without a signature takes and gives `unknown` (TYPE.GRADUAL).
2625
+ *
2626
+ * A check of types trusts the signatures. Each operation must give a member of the result of each signature that
2627
+ * its arguments match. The hook `check` must keep each result in that type.
1912
2628
  */
1913
2629
  interface FormulaProfile {
1914
2630
  readonly ops?: Readonly<Record<string, OpFn>> | ((name: string) => OpFn | undefined);
@@ -1921,6 +2637,22 @@ interface FormulaProfile {
1921
2637
  readonly missing?: (value: unknown) => boolean;
1922
2638
  readonly check?: (value: unknown, op: string) => Result | undefined;
1923
2639
  readonly combine?: (errors: readonly EvalError[]) => EvalError;
2640
+ readonly pure?: true | readonly string[];
2641
+ readonly volatile?: readonly string[];
2642
+ readonly sigs?: Readonly<Record<string, Signature | readonly Signature[]>> | ((name: string) => Signature | readonly Signature[] | undefined);
2643
+ }
2644
+ /**
2645
+ * The signature of an operation: the value types of its parameters and of its result (TYPE.SIGNATURE). A parameter of
2646
+ * the type `unknown` at the end of `params` is optional. A later version can add a key, for example the type that a
2647
+ * true result proves.
2648
+ */
2649
+ interface Signature {
2650
+ /** The types of the parameters, in order. */
2651
+ readonly params: readonly ValueType[];
2652
+ /** The type of each argument after the parameters. Without it, the operation takes no more arguments. */
2653
+ readonly rest?: ValueType;
2654
+ /** The type of the result. */
2655
+ readonly to: ValueType;
1924
2656
  }
1925
2657
  /** The value of a name whose binding failed. A reference to the name gives the error. */
1926
2658
  export declare class Held {
@@ -1941,7 +2673,10 @@ type Closure = ((...args: readonly unknown[]) => unknown) & {
1941
2673
  * @returns `true` for a closure.
1942
2674
  */
1943
2675
  export declare function isClosure(value: unknown): value is Closure;
1944
- /** The standard extensions: the values that JSON cannot write. */
2676
+ /**
2677
+ * The standard extensions: the values that JSON cannot write. `ext.domain` reads a member of a domain through the
2678
+ * codec of the domain (EXT.DOMAIN, D40).
2679
+ */
1945
2680
  export declare const STD_EXT: Readonly<Record<string, ExtFn>>;
1946
2681
  /** The truth of a value in the rules of JavaScript: `0`, `""`, `null`, `undefined` and `NaN` are false. */
1947
2682
  export declare function jsTruthy(value: unknown): boolean;
@@ -1954,7 +2689,7 @@ export declare function jsTruthy(value: unknown): boolean;
1954
2689
  export declare function formulaKinds(): Readonly<Record<string, WorldEntry>>;
1955
2690
  /**
1956
2691
  * This function makes the evaluators of the formula kit for one language. Each evaluator compiles its document
1957
- * one time into code.
2692
+ * one time into code. Each evaluator also holds its type rule, for a check of types (TYPE.SYNTH).
1958
2693
  *
1959
2694
  * @param profile - The operations and the rules of the language.
1960
2695
  * @returns The evaluators, by their name.
@@ -1971,16 +2706,31 @@ export declare function formulaEvaluators(profile?: FormulaProfile): Readonly<Re
1971
2706
  * @returns The hook: `true`, or the reason of the `#NAME?` that the evaluator gives in a run.
1972
2707
  */
1973
2708
  export declare function formulaKnown(profile?: FormulaProfile): (path: readonly Key[], evaluator: string) => true | string;
2709
+ /**
2710
+ * This function makes the hook `facts` of the formula kit for one profile (FACTS.PROFILE, D24). It answers for the
2711
+ * operations and the extensions, because one fallback kind covers each of them.
2712
+ *
2713
+ * - An operation of `lazy` has a lazy rule for each argument.
2714
+ * - An operation is pure when the profile names it in `pure`, or when `pure` is `true`. A volatile operation is not pure.
2715
+ * - A standard extension is pure. An extension of the profile gets the context, thus it is not pure.
2716
+ *
2717
+ * @param profile - The operations, the extensions and their facts.
2718
+ * @returns The hook: the facts of a name, or `undefined` for the facts of the contract.
2719
+ */
2720
+ export declare function formulaFacts(profile?: FormulaProfile): (path: readonly Key[], code: string) => KindFacts | undefined;
1974
2721
  /**
1975
2722
  * This function makes a machine for a formula language. It merges the kit and the parts that the language adds with
1976
2723
  * `mergeMachines`. Thus a kind `ops.*` or a namespace `ops` of the language extends the namespace of the kit, and
1977
2724
  * the fallback of the kit stays. The hook `known` of the kit comes from the profile (`formulaKnown`). A hook `known`
1978
- * of the language answers after it.
2725
+ * of the language answers after it. The hook `facts` of the kit comes from the profile too (`formulaFacts`).
1979
2726
  *
1980
2727
  * A kind or an evaluator of the language that differs from the entry of the kit with its name is a conflict. The
1981
2728
  * language names the path in `replaces` to replace the entry, for example `["world", "kinds", "ref"]` or
1982
2729
  * `["evaluators", "formula.op"]`. Then the hook of the kit does not answer for a replaced evaluator.
1983
2730
  *
2731
+ * The kit gives the domains of the kernel (`STD_DOMAINS`). Thus a domain of the language with the name `number` is a
2732
+ * conflict. The language names `["domains", "number"]` in `replaces` to replace it.
2733
+ *
1984
2734
  * @param profile - The operations and the rules of the language.
1985
2735
  * @param more - The parts of a machine that the language adds, with the paths of the entries that it replaces.
1986
2736
  * @returns The machine.
@@ -1988,6 +2738,189 @@ export declare function formulaKnown(profile?: FormulaProfile): (path: readonly
1988
2738
  */
1989
2739
  export declare function formulaMachine(profile?: FormulaProfile, more?: MachinePart): Machine;
1990
2740
  //#endregion
2741
+ //#region src/codec.d.ts
2742
+ /** The domains of a machine, by their names. */
2743
+ type Domains = Readonly<Record<string, Domain>> | undefined;
2744
+ /**
2745
+ * This function reads the value of an extension `ext.domain` (EXT.DOMAIN). The value is a record with only the text
2746
+ * `domain` and the JSON `data`. The codec of the named domain reads the data, and the result must be a member of the
2747
+ * domain.
2748
+ *
2749
+ * @param data - The value of the extension document.
2750
+ * @param domains - The domains of the machine.
2751
+ * @returns The member, `#NAME?` for a domain without a codec, or `#VALUE!` for data that the codec cannot read.
2752
+ */
2753
+ export declare function decodeDomain(data: Json, domains: Domains): Result;
2754
+ /**
2755
+ * This function writes a host value as a term document of the formula kit (EXT.ENCODE, D40). Thus the same value has
2756
+ * the same document in each language (D12).
2757
+ *
2758
+ * - A value that JSON writes exactly stays as it is. A literal with the shape of an envelope goes into `lit`.
2759
+ * - `NaN`, an infinity and `-0` become `ext.number`, and `undefined` becomes `ext.undefined`.
2760
+ * - A member of a domain with a codec becomes `ext.domain`. The domains go in the order of their names.
2761
+ * - A list or a plain record with such a value becomes the construct `list` or `record`.
2762
+ *
2763
+ * @param machine - The machine, or only its domains.
2764
+ * @param value - The host value.
2765
+ * @returns The document. `decodeValue` gives the value again (EXT.ROUNDTRIP).
2766
+ * @throws {TypeError} The value has a cycle, or it is not JSON and no domain with a codec holds it.
2767
+ */
2768
+ export declare function encodeValue(machine: Pick<Machine, "domains">, value: unknown): Json;
2769
+ /**
2770
+ * This function reads a document of `encodeValue` again: it evaluates the document as a term, in an empty context.
2771
+ * A bare root value is a literal.
2772
+ *
2773
+ * @param machine - A machine of the formula kit, with the domains of the document.
2774
+ * @param doc - The document.
2775
+ * @returns The value, or the error of the evaluation.
2776
+ */
2777
+ export declare function decodeValue(machine: Machine, doc: unknown): Result;
2778
+ //#endregion
2779
+ //#region src/syntax.d.ts
2780
+ /** The place of an operator: before its term, between two terms, or after its term. */
2781
+ type SyntaxFixity = "prefix" | "infix" | "postfix";
2782
+ /**
2783
+ * The grouping of a chain of one infix operator. `left` reads `a - b - c` as `(a - b) - c`, and `right` reads
2784
+ * `a ^ b ^ c` as `a ^ (b ^ c)`. `none` refuses a chain. `flat` reads a chain as one document with each term.
2785
+ */
2786
+ type SyntaxAssoc = "left" | "right" | "none" | "flat";
2787
+ /** One operator of a syntax profile. */
2788
+ interface SyntaxOperator {
2789
+ /** The text of the operator, for example `+`, `<>` or `and`. A word operator is a plain name. */
2790
+ readonly symbol: string;
2791
+ /** The place of the operator. */
2792
+ readonly fixity: SyntaxFixity;
2793
+ /** The precedence. A larger number binds more tightly. */
2794
+ readonly prec: number;
2795
+ /** The grouping of a chain of an infix operator. The default is `left`. */
2796
+ readonly assoc?: SyntaxAssoc;
2797
+ /** The type of the document that the operator makes, with dots between the keys, for example `ops.add` or `and`. */
2798
+ readonly kind: string;
2799
+ }
2800
+ /** The literal rules of a syntax profile. */
2801
+ interface SyntaxLiterals {
2802
+ /** `false` removes the decimal numbers. The default is `true`. */
2803
+ readonly numbers?: boolean;
2804
+ /** `true` puts a minus sign right before a digit into the number, where a term starts. The default is `true`. */
2805
+ readonly signed?: boolean;
2806
+ /** The texts: the quote and the escape of a quote. `false` removes the texts. The default is `"` with backslashes. */
2807
+ readonly strings?: false | {
2808
+ readonly quote?: "\"" | "'";
2809
+ readonly escape?: "backslash" | "double";
2810
+ };
2811
+ /** The words that are literals, with their values. The default is `true`, `false` and `null`. */
2812
+ readonly words?: Readonly<Record<string, unknown>>;
2813
+ }
2814
+ /** A reference syntax that a pattern gives, for example the address `A1` of a cell. */
2815
+ interface SyntaxRefPattern {
2816
+ /** The pattern of the text of a reference. The parser tries it before a name. */
2817
+ readonly pattern: RegExp;
2818
+ /** This function gives the path of the reference from its text. */
2819
+ readonly read: (text: string) => readonly Key[];
2820
+ /** This function gives the text of a path, or `undefined` when the pattern does not write the path. */
2821
+ readonly write: (path: readonly unknown[]) => string | undefined;
2822
+ }
2823
+ /** The reference syntax of a syntax profile. */
2824
+ interface SyntaxRefs {
2825
+ /** The root of a bare name. The default is `names`. Thus `x` is the path `["names", "x"]`. */
2826
+ readonly bare?: string;
2827
+ /** The roots that the text names first, for example `self.price`. The default is `self`, `world`, `event` and `caps`. */
2828
+ readonly roots?: readonly string[];
2829
+ /** `false` removes the field steps `a.b`. The default is `true`. */
2830
+ readonly fields?: boolean;
2831
+ /** The patterns of other references. */
2832
+ readonly patterns?: readonly SyntaxRefPattern[];
2833
+ }
2834
+ /** A call form: a name with arguments in parentheses that makes a construct, for example `if(test, then, else)`. */
2835
+ interface SyntaxForm {
2836
+ /** The name in the text. */
2837
+ readonly name: string;
2838
+ /** The type of the document, with dots between the keys. */
2839
+ readonly kind: string;
2840
+ /** The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. */
2841
+ readonly fields?: readonly string[];
2842
+ /** The smallest number of arguments. The default is the number of the fields, or `0`. */
2843
+ readonly min?: number;
2844
+ }
2845
+ /** The call syntax of a syntax profile. */
2846
+ interface SyntaxCalls {
2847
+ /** The operations that a call `name(args)` can name. `true` permits each name. The default is `true`. */
2848
+ readonly ops?: boolean | readonly string[];
2849
+ /** The call forms of constructs. A form wins over an operation with the same name. */
2850
+ readonly forms?: readonly SyntaxForm[];
2851
+ /** The text between two arguments. The default is `,`. */
2852
+ readonly separator?: string;
2853
+ }
2854
+ /**
2855
+ * The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
2856
+ * reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
2857
+ * and a language read the same rules.
2858
+ */
2859
+ interface SyntaxProfile {
2860
+ /** The operators. */
2861
+ readonly operators?: readonly SyntaxOperator[];
2862
+ /** The literal rules. */
2863
+ readonly literals?: SyntaxLiterals;
2864
+ /** The reference syntax. */
2865
+ readonly refs?: SyntaxRefs;
2866
+ /** The call syntax. */
2867
+ readonly calls?: SyntaxCalls;
2868
+ /** The deepest nesting that `parse` accepts. The default is `256`. */
2869
+ readonly maxDepth?: number;
2870
+ }
2871
+ /** A problem of a text: its character offset, its length and a message. */
2872
+ interface SyntaxIssue {
2873
+ /** The 0-based character offset of the problem. */
2874
+ readonly offset: number;
2875
+ /** The number of characters of the problem. `0` marks a place between two characters. */
2876
+ readonly length: number;
2877
+ /** The message. */
2878
+ readonly message: string;
2879
+ }
2880
+ /** The result of `parse`: a document, or the problems of the text. */
2881
+ type ParseResult = {
2882
+ readonly ok: true;
2883
+ readonly doc: Json;
2884
+ } | {
2885
+ readonly ok: false;
2886
+ readonly issues: readonly SyntaxIssue[];
2887
+ };
2888
+ /**
2889
+ * The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
2890
+ * `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
2891
+ * `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs.
2892
+ */
2893
+ export declare const STD_SYNTAX: SyntaxProfile;
2894
+ /**
2895
+ * This function reads a text into a document with the rules of a profile (SYNTAX.PARSE). It does not throw for a
2896
+ * bad text. The issue gives the offset, the length and a message (SYNTAX.SPAN).
2897
+ *
2898
+ * @param profile - The syntax profile.
2899
+ * @param text - The text.
2900
+ * @returns The document, or the issues of the text.
2901
+ * @throws {TypeError} The profile is not valid, for example an operator has two entries of the same place.
2902
+ */
2903
+ export declare function parse(profile: SyntaxProfile, text: string): ParseResult;
2904
+ /**
2905
+ * This function writes a document as text with the rules of a profile (SYNTAX.PRINT). It writes the fewest
2906
+ * parentheses that keep the tree. `parse` reads the text back to the same document (SYNTAX.ROUNDTRIP).
2907
+ *
2908
+ * @param profile - The syntax profile.
2909
+ * @param doc - The document.
2910
+ * @returns The text, or `#VALUE!` at the place of a document that the profile cannot write.
2911
+ * @throws {TypeError} The profile is not valid.
2912
+ */
2913
+ export declare function print(profile: SyntaxProfile, doc: unknown): Result<string>;
2914
+ /**
2915
+ * This function makes the part of a merge that adds the verb `format` to a machine (D23, D41). Its default writes
2916
+ * each document with the printer of the profile. A part gives its own text through the ladder, thus an own entry or
2917
+ * a kind entry of `format` still wins.
2918
+ *
2919
+ * @param profile - The syntax profile.
2920
+ * @returns The part for `mergeMachines`.
2921
+ */
2922
+ export declare function syntaxFormat(profile: SyntaxProfile): MachinePart;
2923
+ //#endregion
1991
2924
  //#region src/reference.d.ts
1992
2925
  /**
1993
2926
  * The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
@@ -2007,16 +2940,24 @@ interface ReferenceOptions {
2007
2940
  readonly effects?: Effect[];
2008
2941
  /** The mock of the host (RUN.MOCK). It answers each effect at once. Without it, an effect gives its payload. */
2009
2942
  readonly perform?: Perform;
2943
+ /**
2944
+ * The verb that goes up the ladder at each document, as in `prepare`. The default is `eval`. The reference reads
2945
+ * each verb by the same rules (VERB.AGREE).
2946
+ */
2947
+ readonly verb?: string;
2010
2948
  }
2011
2949
  /**
2012
2950
  * This function evaluates a document by the rules, without a compilation. It is the reference of the plans: a plan,
2013
2951
  * a traced plan and the second tier of a language must give its results. It covers evaluations, not runs: an effect
2014
2952
  * gives the answer of the mock or its payload, and a part that waits gives `#CALC!`.
2015
2953
  *
2954
+ * The verb of the options goes up the ladder at each document, as in `prepare`. Each verb has the same rules: the
2955
+ * ladder, the contract of the kind and the sealed parts (VERB.AGREE).
2956
+ *
2016
2957
  * @param machine - The world and the code of the evaluators.
2017
2958
  * @param doc - The document.
2018
2959
  * @param context - The names and the capabilities at the root.
2019
- * @param options - The type of a bare root value, the definitions of compiled code, a list for the effects and a mock.
2960
+ * @param options - The type of a bare root value, the definitions of compiled code, a list for the effects, a mock and the verb.
2020
2961
  * @returns The result.
2021
2962
  */
2022
2963
  export declare function reference(machine: Machine, doc: unknown, context?: Context, options?: ReferenceOptions): Result;
@@ -2054,11 +2995,19 @@ interface TierResult {
2054
2995
  interface TierInput {
2055
2996
  /** The mock of the host, when `agree` has one (AGREE.MOCK). The tier answers each effect with it. */
2056
2997
  readonly perform?: Perform;
2998
+ /** The verb of `agree`, when its options name one (VERB.AGREE). A tier that does not serve the verb fails. */
2999
+ readonly verb?: string;
2057
3000
  }
2058
3001
  /** The options of `agree`. */
2059
3002
  interface AgreeOptions {
2060
3003
  /** The type of a bare root value. */
2061
3004
  readonly declaredType?: string;
3005
+ /**
3006
+ * The verb of each tier, as in `prepare`. The default is `eval`. The plan, the reference, the traced evaluation and a
3007
+ * second evaluation each ask the ladder for this verb (VERB.AGREE). The second tier of a language gets it in its
3008
+ * input.
3009
+ */
3010
+ readonly verb?: string;
2062
3011
  /** The definitional code of the compiled evaluators of the machine, for the reference. */
2063
3012
  readonly definitions?: Definitions;
2064
3013
  /** The tiers to compare with the plan. The default is the reference, the traced evaluation and a second evaluation. */
@@ -2068,7 +3017,7 @@ interface AgreeOptions {
2068
3017
  *
2069
3018
  * @param doc - The document.
2070
3019
  * @param context - The context.
2071
- * @param input - The mock of the host, when `agree` has one.
3020
+ * @param input - The mock of the host and the verb, when `agree` has them.
2072
3021
  * @returns The result, or the result with the effects.
2073
3022
  */
2074
3023
  readonly other?: (doc: unknown, context: Context, input: TierInput) => Result | TierResult;
@@ -2144,6 +3093,110 @@ export declare function sameValue(a: unknown, b: unknown, equal?: (a: unknown, b
2144
3093
  */
2145
3094
  export declare function agree(machine: Machine, doc: unknown, context?: Context, options?: AgreeOptions): Agreement;
2146
3095
  //#endregion
3096
+ //#region src/conform.d.ts
3097
+ /**
3098
+ * An obligation that `conforms` checks. `C1` to `C8` are the obligations of host code in `docs/SEMANTICS.md`. `local`
3099
+ * and `agree` are two premises of the simulation of the plan (SIM-PLAN).
3100
+ *
3101
+ * - `C1`: each context that the code gives a part, or an effect, has only the capabilities of its document.
3102
+ * - `C2`: the code causes only the effects that the contract of the kind declares.
3103
+ * - `C3`: each eager part evaluates when the result is a value, and a lazy part evaluates only when its result counts.
3104
+ * - `C4`: the code of a pure kind causes no effect, and it reads the context only through `resolve`.
3105
+ * - `C5`: the code reads its parts only through their handles, not through the JSON of the document.
3106
+ * - `C6`: only a runner waits, and a runner passes each wait of its parts and its effects through.
3107
+ * - `C7`: the code binds for a part each name that the scope rules give the part, and no other name.
3108
+ * - `C8`: compiled code gives the result of code that compiles again at the time of the evaluation.
3109
+ * - `local`: the code keeps no state from one call to the next.
3110
+ * - `agree`: compiled code gives the result of its definition for the reference interpreter.
3111
+ */
3112
+ type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree";
3113
+ /** The probe of a finding: the document, the result of each probe part, the capabilities and the handler. */
3114
+ interface ConformProbe {
3115
+ /** The text of the type of the document. */
3116
+ readonly type: string;
3117
+ /** The document. A probe document takes the place of each part. */
3118
+ readonly doc: Envelope;
3119
+ /** The result of each probe part, by the key of the part. */
3120
+ readonly results: Readonly<Record<string, Result>>;
3121
+ /** The keys of the probe parts that wait for the host before they give their result. Only a run has them. */
3122
+ readonly waits: readonly string[];
3123
+ /** The capabilities of the context of the document. */
3124
+ readonly caps: readonly Cap[];
3125
+ /** `true` in a run, in which the host does each effect and a part can wait. */
3126
+ readonly running: boolean;
3127
+ }
3128
+ /** One obligation that the code breaks, with the reason and the first probe that shows it. */
3129
+ interface Finding {
3130
+ readonly obligation: Obligation;
3131
+ /** One or two sentences that tell what the code did. */
3132
+ readonly reason: string;
3133
+ readonly probe: ConformProbe;
3134
+ }
3135
+ /** The options of `conforms`. */
3136
+ interface ConformOptions {
3137
+ /**
3138
+ * The verb that the evaluator serves. The default is `eval`. The facts of a contract (`effects`, `pure` and `lazy`)
3139
+ * describe only `eval`, thus `conforms` checks C2, C3 and C4 only for `eval` (D23).
3140
+ */
3141
+ readonly verb?: string;
3142
+ /**
3143
+ * The types of the probe documents. The default is each kind of the world whose verb names the evaluator. A fallback
3144
+ * kind gives the key `probe`, for example `["ops", "probe"]`. The contract of the kind of each type applies.
3145
+ */
3146
+ readonly types?: readonly TypeRef[];
3147
+ /**
3148
+ * More values of probe documents, by the text of their type. A probe document takes the place of each part of such a
3149
+ * value. Use them for data that the code needs, for example the key of `write`.
3150
+ */
3151
+ readonly values?: Readonly<Record<string, readonly Json[]>>;
3152
+ /**
3153
+ * The results that a probe part can give. The default holds numbers, truth values, a text, `null`, a list, a
3154
+ * record, a function and two errors.
3155
+ */
3156
+ readonly results?: readonly Result[];
3157
+ /**
3158
+ * The definitional code of the compiled evaluators and runners, as for `reference`. A standard evaluator gets its
3159
+ * definition from `STD_DEFINITIONS`.
3160
+ */
3161
+ readonly definitions?: Definitions;
3162
+ /** The capabilities of half of the probes. The other half has none. The default is the declared effects and `probe`. */
3163
+ readonly caps?: readonly Cap[];
3164
+ /** The names of the context of each probe. */
3165
+ readonly names?: Readonly<Record<string, unknown>>;
3166
+ /** The seed of the random results. The same seed gives the same probes. The default is 1. */
3167
+ readonly seed?: number;
3168
+ /** The count of probes with random results for each probe document. The default is 12. */
3169
+ readonly runs?: number;
3170
+ /** The mock of the host (RUN.MOCK). It answers each effect at once. Without it, an effect gives its payload. */
3171
+ readonly perform?: Perform;
3172
+ /**
3173
+ * This function compares two values that the rules of `sameValue` do not know, as in `agree`.
3174
+ *
3175
+ * @param a - The first value.
3176
+ * @param b - The second value.
3177
+ * @returns `true` or `false`, or `undefined` for the rules of `sameValue`.
3178
+ */
3179
+ readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
3180
+ }
3181
+ /**
3182
+ * This function examines one evaluator or runner of a machine against the obligations of host code (K92, D36). It
3183
+ * starts the code directly, without the kernel, with probe parts and a probe runtime. It generates probe documents from
3184
+ * the contract of each kind that names the code, and it gives the probe parts chosen and random results.
3185
+ *
3186
+ * The checks follow the obligations C1 to C8 of `docs/SEMANTICS.md`. Two more checks follow the premises of the
3187
+ * simulation of the plan. The check `local` finds state that stays from one call to the next. The check `agree` compares
3188
+ * compiled code with its definition. The
3189
+ * finding of an obligation names the first probe that breaks it. An empty list means that each probe conforms.
3190
+ *
3191
+ * @param machine - The machine with the code and the world of the kinds.
3192
+ * @param name - The name of the evaluator or of the runner. A runner wins over an evaluator of the same name.
3193
+ * @param options - The verb, the types and the values of the probe documents, and the results of the probe parts. Also
3194
+ * the definitions, the capabilities, the names, the seed, the mock and the rule of equality.
3195
+ * @returns The first finding of each obligation that the code breaks, in the order of the obligations.
3196
+ * @throws {Error} The machine has no code with the name, or no kind names it and the options give no types.
3197
+ */
3198
+ export declare function conforms(machine: Machine, name: string, options?: ConformOptions): readonly Finding[];
3199
+ //#endregion
2147
3200
  //#region src/same.d.ts
2148
3201
  /**
2149
3202
  * This function tells if two results are the same for an early cutoff (RESULT.SAME). A schedule uses it to stop the
@@ -2167,6 +3220,422 @@ export declare function agree(machine: Machine, doc: unknown, context?: Context,
2167
3220
  */
2168
3221
  export declare function sameResult(a: Result<unknown>, b: Result<unknown>, equal?: (a: unknown, b: unknown) => boolean | undefined): boolean;
2169
3222
  //#endregion
3223
+ //#region src/reads.d.ts
3224
+ /** The answer of `verifyReads`: the old result stays valid, or the first read that reaches another thing. */
3225
+ type ReadsCheck = {
3226
+ readonly same: true;
3227
+ } | {
3228
+ readonly same: false;
3229
+ /** The index of the first changed read in the list. */
3230
+ readonly index: number;
3231
+ /** The first changed read, as the evaluation recorded it. */
3232
+ readonly read: Read;
3233
+ /** What the path of that read reaches in the new context. */
3234
+ readonly now: Result;
3235
+ };
3236
+ /** The options of `verifyReads`. */
3237
+ interface VerifyOptions {
3238
+ /**
3239
+ * The rule of the host for two things, as in `sameResult`. It answers first, and `undefined` gives the rules of
3240
+ * `sameResult`. An example is a rule for a host thing that keeps a version.
3241
+ *
3242
+ * @param a - The thing of the recorded read.
3243
+ * @param b - The thing in the new context.
3244
+ * @returns `true` when the two things are the same, or `undefined` for the rules of `sameResult`.
3245
+ */
3246
+ readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
3247
+ }
3248
+ /**
3249
+ * This function tells if an old result stays valid in a new context (READS.VERIFY, D26). It resolves the path of
3250
+ * each free read again, in the order of the list, and it compares what the path reaches with `sameResult`. It stops at
3251
+ * the first read that reaches another thing, and it gives that read (READS.CHANGED).
3252
+ *
3253
+ * - A read that is not free reads a binding that a kind made from earlier reads, for example a name of `let`. The
3254
+ * function does not resolve it again.
3255
+ * - A thing compares as in `sameResult`. Thus a host thing or a date is the same only as itself. A host gives a new
3256
+ * object for a new state, or the option `equal`.
3257
+ * - A longer path through a name that holds a `Held` in the new context is a changed read. A reference of the formula
3258
+ * kit gives the error of that binding, and the resolution of the path does not show it.
3259
+ * - The answer is sound only for a pure document (FACTS.PURE). A document with an effect, a volatile operation or an
3260
+ * extension of a profile can read outside `resolve`. The schedule asks `factsOf` first.
3261
+ *
3262
+ * The values of the context must not change in place, as PLAN.CACHE says for the documents. A value that changed in
3263
+ * place is the same object, thus the function cannot see the change.
3264
+ *
3265
+ * @param target - The machine of the evaluation, or its plan.
3266
+ * @param reads - The reads of the evaluation, from the option `reads`.
3267
+ * @param context - The new context.
3268
+ * @param options - The rule of the host for two things.
3269
+ * @returns `{ same: true }` when each free read reaches the same thing, or else the first changed read.
3270
+ */
3271
+ export declare function verifyReads(target: Machine | Plan, reads: readonly Read[], context: Context, options?: VerifyOptions): ReadsCheck;
3272
+ //#endregion
3273
+ //#region src/durable.d.ts
3274
+ /** The two epochs of a host (DURABLE.EPOCHS). Each epoch counts the changes of its level. */
3275
+ interface Epochs {
3276
+ /** The count of the changes of the structure: a new machine, or an edit of a document. */
3277
+ readonly structure: number;
3278
+ /** The count of the changes of the data. A change of the structure is also a change of the data. */
3279
+ readonly data: number;
3280
+ }
3281
+ /** The work of a durable cache since its start. A schedule reads it as a measure, not as a rule (R4). */
3282
+ interface DurableCounts {
3283
+ /** The compilations: the calls of `prepare`. */
3284
+ readonly compiles: number;
3285
+ /** The calls of `factsOf`. */
3286
+ readonly facts: number;
3287
+ /** The evaluations of a plan. */
3288
+ readonly evaluations: number;
3289
+ /** The calls of `verifyReads`. */
3290
+ readonly verifications: number;
3291
+ /** The results that stayed without an evaluation. */
3292
+ readonly reuses: number;
3293
+ }
3294
+ /** The options of `durable`. */
3295
+ interface DurableOptions {
3296
+ /** The type of a bare root value, for each plan and each fact. */
3297
+ readonly declaredType?: string;
3298
+ /** The verb of each plan and each fact. The default is `eval` (VERB.PREPARE). */
3299
+ readonly verb?: string;
3300
+ /** The volatile reads of the host, as in `factsOf`. A document with such a read is not pure, thus it evaluates again after each change of data. */
3301
+ readonly volatile?: FactsOptions["volatile"];
3302
+ /** The rule of the host for two things, as in `verifyReads`. */
3303
+ readonly equal?: VerifyOptions["equal"];
3304
+ }
3305
+ /**
3306
+ * A cache of plans, facts and results with two levels of durability (D30). A host or a schedule tells the cache each
3307
+ * change of the structure and each change of the data.
3308
+ */
3309
+ interface Durable {
3310
+ /** The machine of the current structure epoch. */
3311
+ readonly machine: Machine;
3312
+ /** The current epochs. A schedule builds again what depends on the whole structure when `structure` changes, for example a graph of the nodes. */
3313
+ readonly epochs: Epochs;
3314
+ /** The work since the start. */
3315
+ readonly counts: DurableCounts;
3316
+ /**
3317
+ * This function gives the plan of a document. A document object compiles one time for a machine (DURABLE.STRUCTURE).
3318
+ * A change of data compiles nothing (DURABLE.DATA).
3319
+ *
3320
+ * @param doc - The document, as JSON.
3321
+ * @returns The plan.
3322
+ */
3323
+ plan(doc: unknown): Plan;
3324
+ /**
3325
+ * This function gives the static facts of a document. A document object computes its facts one time for a machine.
3326
+ *
3327
+ * @param doc - The document, as JSON.
3328
+ * @returns The facts.
3329
+ */
3330
+ facts(doc: unknown): DocFacts;
3331
+ /**
3332
+ * This function gives the result of the document of a node (DURABLE.REUSE). The key names the node, and in one data
3333
+ * epoch the context of a key gives the same data.
3334
+ *
3335
+ * - In the data epoch of its result, a key with the same plan gives that result again.
3336
+ * - After a change of data, a pure document verifies its reads, and it keeps its result when each read is the same.
3337
+ * - Each other document evaluates again.
3338
+ *
3339
+ * @param key - The name of the node in the host, for example the name of a cell.
3340
+ * @param doc - The document of the node.
3341
+ * @param context - The context of the node.
3342
+ * @returns The result.
3343
+ */
3344
+ evaluate(key: unknown, doc: unknown, context: Context): Result;
3345
+ /** This function tells the cache that the data changed: a context gives a new value (DURABLE.EPOCHS). */
3346
+ changeData(): void;
3347
+ /**
3348
+ * This function tells the cache that the structure changed (DURABLE.EPOCHS). An edit of a document gives a new
3349
+ * document object, and only that object compiles. A new machine drops each plan, each fact and each result.
3350
+ *
3351
+ * @param machine - The new machine, or `undefined` for an edit of a document.
3352
+ */
3353
+ changeStructure(machine?: Machine): void;
3354
+ /**
3355
+ * This function drops the result of a node, for example a node that the host removed.
3356
+ *
3357
+ * @param key - The name of the node.
3358
+ */
3359
+ forget(key: unknown): void;
3360
+ }
3361
+ /**
3362
+ * This function makes a cache with two levels of durability for a host or a schedule (R4 P7, D30). The structure is
3363
+ * the machine and the documents. The data is each value that a context gives: the names, `self`, `event`, the
3364
+ * capabilities and the world of the host.
3365
+ *
3366
+ * - A plan and the facts depend only on the structure. A document object compiles one time for a machine, thus a
3367
+ * change of data compiles nothing (DURABLE.DATA).
3368
+ * - A result depends on the data too. It stays in its data epoch. After a change of data, a pure document verifies
3369
+ * its reads with `verifyReads`, and each other document evaluates again.
3370
+ * - An edit gives a new document object, thus only that document compiles. A new machine drops each plan, each fact
3371
+ * and each result (DURABLE.STRUCTURE).
3372
+ *
3373
+ * The host keeps two promises. In one data epoch, the context of a key gives the same data. The values of a
3374
+ * context and the documents do not change in place, as PLAN.CACHE and `verifyReads` say.
3375
+ *
3376
+ * @param machine - The machine of the first structure epoch.
3377
+ * @param options - The type of a bare root value, the verb, the volatile reads and the rule of the host for two things.
3378
+ * @returns The cache.
3379
+ */
3380
+ export declare function durable(machine: Machine, options?: DurableOptions): Durable;
3381
+ //#endregion
3382
+ //#region src/schedule.d.ts
3383
+ /** One edge of a graph of nodes: a static read of a node from the document of another node (SCHED.EDGES). */
3384
+ interface NodeEdge {
3385
+ /**
3386
+ * The node that the read reaches: the first key after the root `world`. It is `undefined` when the read can reach
3387
+ * each node, for example the path `["world"]`, or a step document right after the root.
3388
+ */
3389
+ readonly to: string | undefined;
3390
+ /** The keys after the node, up to the first step document: the field of the node that the read reaches (SCHED.GRAIN). */
3391
+ readonly field: readonly Key[];
3392
+ /** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
3393
+ readonly lazy: boolean;
3394
+ /** The static read of `factsOf`, with its path, its place and its mark `exact`. */
3395
+ readonly read: StaticRead;
3396
+ }
3397
+ /** One node of a schedule, with what the static facts tell about it (SCHED.GRAPH). */
3398
+ interface NodeInfo {
3399
+ /** The name of the node: its key under the root `world`. */
3400
+ readonly id: string;
3401
+ /** The document of the node. */
3402
+ readonly doc: unknown;
3403
+ /** The static facts of the document. */
3404
+ readonly facts: DocFacts;
3405
+ /** The side of the node, from the facts. A node on the run side is a sink: no node reads it (SCHED.SIDE). */
3406
+ readonly side: Side;
3407
+ /** The edges to the nodes that the document can read, in the order of its reads. */
3408
+ readonly edges: readonly NodeEdge[];
3409
+ }
3410
+ /** The options of `schedule`: the options of `durable`, and the context of the host. */
3411
+ interface ScheduleOptions extends DurableOptions {
3412
+ /** The context of the host: the names, `self`, `event` and the capabilities. The schedule sets the root `world` to the nodes. */
3413
+ readonly context?: Context;
3414
+ }
3415
+ /** The work of a schedule since its start: the work of its `durable` cache, and the demands ahead of a node. */
3416
+ interface ScheduleCounts extends DurableCounts {
3417
+ /**
3418
+ * The demands that a demand of the host made before its own node (SCHED.LONG-CHAIN). Each node that the eager edges
3419
+ * reach, and that has no value in the data epoch, adds one.
3420
+ */
3421
+ readonly ahead: number;
3422
+ }
3423
+ /** The options of a run of a node. */
3424
+ interface NodeRunOptions {
3425
+ /** The event that starts the run, at the root `event`. The default is the event of the context of the host. */
3426
+ readonly event?: Thing;
3427
+ /** The host code that does each effect, as in `run`. */
3428
+ readonly perform?: Perform;
3429
+ /** A signal that stops the run. */
3430
+ readonly signal?: StopSignal;
3431
+ }
3432
+ /**
3433
+ * The demand schedule of a graph of named nodes (D31). The host tells it each change of a node, of the machine and of
3434
+ * its data. The schedule evaluates a node only when a host or another node reads it.
3435
+ */
3436
+ interface Schedule {
3437
+ /** The epochs of the schedule (DURABLE.EPOCHS). A schedule builds again what depends on the structure when `structure` changes. */
3438
+ readonly epochs: Epochs;
3439
+ /** The work of the schedule since its start: the compilations, the evaluations, the verifications, the reuses and the demands ahead. */
3440
+ readonly counts: ScheduleCounts;
3441
+ /** The context of each node in the current data epoch: the context of the host, with the nodes at the root `world`. */
3442
+ readonly context: Context;
3443
+ /**
3444
+ * This function gives each node with its facts, its side and its edges (SCHED.GRAPH). The map stays the same object
3445
+ * in one structure epoch, thus a schedule can keep what it computes from it, for example an order.
3446
+ *
3447
+ * @returns The nodes, by name.
3448
+ */
3449
+ graph(): ReadonlyMap<string, NodeInfo>;
3450
+ /**
3451
+ * This function gives the value of a node on demand (SCHED.DEMAND). A read of `world` in the document demands that
3452
+ * node first. Each node evaluates at most one time in a data epoch.
3453
+ *
3454
+ * - First, the schedule demands each node that the eager edges reach, deepest first (SCHED.LONG-CHAIN).
3455
+ * - After a change, a pure node verifies its reads, and it keeps its result when each read is the same (SCHED.STALE).
3456
+ * - Each node of a cycle gives `#CYCLE!`, in each order of demands (SCHED.CYCLE).
3457
+ * - A node on the run side gives `#REF!`, because the schedule does not evaluate it (SCHED.SIDE).
3458
+ *
3459
+ * @param id - The name of the node.
3460
+ * @returns The result, or `#N/A` for a node that the schedule does not have.
3461
+ */
3462
+ read(id: string): Result;
3463
+ /**
3464
+ * This function adds a node, or gives a node a new document. It is a change of the structure. Only a new document
3465
+ * object compiles (DURABLE.STRUCTURE).
3466
+ *
3467
+ * @param id - The name of the node.
3468
+ * @param doc - The document of the node. It must not change in place after this call.
3469
+ */
3470
+ set(id: string, doc: unknown): void;
3471
+ /**
3472
+ * This function removes a node. It is a change of the structure, and a read of the node then gives `#N/A`.
3473
+ *
3474
+ * @param id - The name of the node.
3475
+ * @returns `true` when the schedule had the node.
3476
+ */
3477
+ remove(id: string): boolean;
3478
+ /**
3479
+ * This function tells the schedule that the data of the host changed (DURABLE.EPOCHS). The values of a context do
3480
+ * not change in place, thus new data comes in a new context, or through a host thing.
3481
+ *
3482
+ * @param context - The new context of the host, or `undefined` to keep the context.
3483
+ */
3484
+ changeData(context?: Context): void;
3485
+ /**
3486
+ * This function gives the schedule a new machine. It drops each plan, each fact and each result.
3487
+ *
3488
+ * @param machine - The new machine.
3489
+ */
3490
+ changeMachine(machine: Machine): void;
3491
+ /**
3492
+ * This function starts a run of the document of a node, and the host does each effect (SCHED.RUN). Only the host
3493
+ * starts a run, for example at an event. A change of data does not start or repeat a run (L3).
3494
+ *
3495
+ * @param id - The name of the node.
3496
+ * @param options - The event, the host code that does the effects, and a signal to stop the run.
3497
+ * @returns The result, when the run ends.
3498
+ */
3499
+ run(id: string, options?: NodeRunOptions): Promise<Result>;
3500
+ }
3501
+ /**
3502
+ * This function gives the edges of a node from the static facts of its document (SCHED.EDGES). Each read of the root
3503
+ * `world` is an edge to the node of its first key. The keys after that key are the field of the edge (SCHED.GRAIN).
3504
+ * A read of another root reads the data of the host, thus it is not an edge.
3505
+ *
3506
+ * A reference in the value of a node can lead a read to a third node (DEREF.COLLAPSE). The edges do not show such a
3507
+ * read, but the reads of an evaluation do (S1d).
3508
+ *
3509
+ * @param facts - The static facts of the document of the node.
3510
+ * @returns The edges, in the order of the reads.
3511
+ */
3512
+ export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
3513
+ /**
3514
+ * This function makes the demand schedule of a graph of named nodes (S1, R4, D31). A host gives each node a name and
3515
+ * a document. The root `world` of each node reaches the other nodes by name. The context of the host gives the other
3516
+ * roots.
3517
+ *
3518
+ * - `graph()` gives the facts, the side and the edges of each node, from `factsOf` and `edgesOf`.
3519
+ * - `read(id)` evaluates a node on demand, through `durable`. A pure node verifies its reads after a change, and a
3520
+ * read of a node demands that node again. Thus only a node with a changed read evaluates again: the red-green
3521
+ * algorithm of rustc.
3522
+ * - A node is on a cycle when its demand reaches itself through the reads of the evaluations. Each node of such a
3523
+ * strongly connected component gives `#CYCLE!`, whatever its document does with the error. The schedule finds the
3524
+ * components with the algorithm of Tarjan over the demands. Thus each order of demands gives the same values.
3525
+ * - A demand of the host, or of a run, first demands each node that the eager edges reach, deepest first. Thus each
3526
+ * read of such a node finds a value, and a chain of 100000 nodes does not overflow the stack (SCHED.LONG-CHAIN).
3527
+ * Each such demand starts with no node in evaluation, thus the order of demands keeps the values of D31.
3528
+ * - A node on the run side is a sink. Only `run` evaluates it, and only the host uses `run`.
3529
+ *
3530
+ * The host keeps the promises of `durable`. The documents and the values of a context do not change in place.
3531
+ *
3532
+ * @param machine - The machine of the first structure epoch.
3533
+ * @param options - The options of `durable`, and the context of the host.
3534
+ * @returns The schedule.
3535
+ */
3536
+ export declare function schedule(machine: Machine, options?: ScheduleOptions): Schedule;
3537
+ //#endregion
3538
+ //#region src/graph.d.ts
3539
+ /** One edge of a graph of nodes: a read of a node by another node. `NodeEdge` of a schedule is such an edge. */
3540
+ interface GraphEdge<Id> {
3541
+ /** The node that the read reaches. It is `undefined` when the read can reach each node (GRAPH.UNKNOWN). */
3542
+ readonly to: Id | undefined;
3543
+ /** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
3544
+ readonly lazy: boolean;
3545
+ }
3546
+ /** One node of a graph, with its edges. `NodeInfo` of a schedule is such a node. */
3547
+ interface GraphNode<Id> {
3548
+ /** The edges to the nodes that the node reads. */
3549
+ readonly edges: readonly GraphEdge<Id>[];
3550
+ /** The side of the node. A node on the run side is a sink: no edge reaches it (SCHED.SIDE). The default is `derive`. */
3551
+ readonly side?: Side;
3552
+ }
3553
+ /**
3554
+ * A graph of nodes, by name. The order of the map is the order of the nodes in each answer. The function `graph` of
3555
+ * a schedule gives such a graph. An edge to a name that is not in the map, or to a sink, is not an edge of the
3556
+ * analysis.
3557
+ */
3558
+ type NodeGraph<Id> = ReadonlyMap<Id, GraphNode<Id>>;
3559
+ /** The options of an analysis. */
3560
+ interface GraphOptions {
3561
+ /**
3562
+ * `true`: the analysis keeps only the eager edges with a target node. Such a read occurs in each evaluation in
3563
+ * which each document around it gives a value (FACTS.LAZY). The default keeps each edge.
3564
+ */
3565
+ readonly eager?: boolean;
3566
+ }
3567
+ /** One static cycle of a graph (GRAPH.CYCLE). */
3568
+ interface GraphCycle<Id> {
3569
+ /** The nodes of the cycle, in the order of the graph. */
3570
+ readonly nodes: readonly Id[];
3571
+ /**
3572
+ * `true` when the eager edges with a target close the cycle. `false` when the cycle needs a lazy edge or an edge
3573
+ * without a target. The value of each node still comes from the demand (D31).
3574
+ */
3575
+ readonly certain: boolean;
3576
+ }
3577
+ /**
3578
+ * This function gives the strongly connected components of a graph of nodes (GRAPH.SCC), with the algorithm of
3579
+ * Tarjan. It keeps its own stack, thus a chain of 100000 nodes does not overflow the stack of the host.
3580
+ *
3581
+ * - Each component comes after each component that it reads: the deepest component comes first.
3582
+ * - A node that is on no cycle is a component of one node.
3583
+ * - The nodes of a component are in the order of the graph.
3584
+ *
3585
+ * @param graph - The nodes, each with its edges.
3586
+ * @param options - The option `eager` keeps only the eager edges with a target node.
3587
+ * @returns The components, deepest first.
3588
+ */
3589
+ export declare function components<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
3590
+ /**
3591
+ * This function gives the height of each node: the order of a push schedule (GRAPH.ORDER). A schedule that evaluates
3592
+ * the nodes from the lowest height up evaluates each node after each node that it reads, except on a cycle.
3593
+ *
3594
+ * - A node that reads no node outside its component has the height 0.
3595
+ * - Each other node is one higher than the highest node that it reads outside its component.
3596
+ * - The nodes of one component have one height.
3597
+ * - An edge without a target reads each node that is not a sink (GRAPH.UNKNOWN).
3598
+ *
3599
+ * @param graph - The nodes, each with its edges.
3600
+ * @param options - The option `eager` keeps only the eager edges with a target node.
3601
+ * @returns The height of each node, in the order of the graph.
3602
+ */
3603
+ export declare function heights<Id>(graph: NodeGraph<Id>, options?: GraphOptions): ReadonlyMap<Id, number>;
3604
+ /**
3605
+ * This function puts the nodes in layers by their heights, in linear time (GRAPH.LAYERS). The first layer has the
3606
+ * height 0. Two nodes of one layer read each other only inside one component. Thus a push schedule can evaluate the
3607
+ * components of one layer at the same time.
3608
+ *
3609
+ * @param graph - The nodes, each with its edges.
3610
+ * @param options - The option `eager` keeps only the eager edges with a target node.
3611
+ * @returns The layers, from the height 0 up. Each layer keeps the order of the graph.
3612
+ */
3613
+ export declare function nodeLayers<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
3614
+ /**
3615
+ * This function gives the nodes that a set of observed nodes needs (GRAPH.NECESSARY). These are the observed nodes,
3616
+ * and each node with a path of edges from them. A push schedule evaluates only these nodes. An observed name that is
3617
+ * not a node of the graph adds nothing.
3618
+ *
3619
+ * @param graph - The nodes, each with its edges.
3620
+ * @param observed - The nodes that the host shows or reads.
3621
+ * @param options - The option `eager` keeps only the eager edges with a target node.
3622
+ * @returns The necessary nodes, in the order of the graph.
3623
+ */
3624
+ export declare function necessary<Id>(graph: NodeGraph<Id>, observed: Iterable<Id>, options?: GraphOptions): ReadonlySet<Id>;
3625
+ /**
3626
+ * This function gives the static cycles of a graph (GRAPH.CYCLE): each component with two or more nodes, and each
3627
+ * node with an edge to itself. A cycle of the eager edges with a target is certain, and `check` or a host can report
3628
+ * it before a run. Another cycle is possible: an evaluation can skip a lazy read.
3629
+ *
3630
+ * - A component of all the edges that is also a component of the eager edges is one certain cycle.
3631
+ * - Each other component of all the edges is one possible cycle, and each certain cycle in it comes after it.
3632
+ * - A read can still fail before it occurs. Thus the demand of D31, not a static cycle, gives the value of each node.
3633
+ *
3634
+ * @param graph - The nodes, each with its edges.
3635
+ * @returns The cycles, deepest first.
3636
+ */
3637
+ export declare function cycles<Id>(graph: NodeGraph<Id>): readonly GraphCycle<Id>[];
3638
+ //#endregion
2170
3639
  //#region src/replay.d.ts
2171
3640
  /** One effect of a log: its address, its request and its outcome. */
2172
3641
  interface ReplayEntry {
@@ -2314,5 +3783,53 @@ export declare function typesOf(world: World): readonly (readonly Key[])[];
2314
3783
  */
2315
3784
  export declare function generate(world: World, options: GenerateOptions): unknown;
2316
3785
  //#endregion
2317
- export type { AgreeOptions, Agreement, Alias, AllOptions, Answer, AskOptions, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocParts, DocVisit, Edge, Effect, Envelope, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, Failed, FormulaProfile, GenerateOptions, Give, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindSource, LazyOp, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, OpFn, OrderProblem, Outcome, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartsSpec, Perform, Plan, PrepareOptions, Random, Recorder, RefUse, ReferenceOptions, ReplayEntry, ReplayLog, ReplayOptions, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, ScopeRule, Shape$1 as Shape, Side, Split, Step, StepSpec, Steps, StopSignal, Stored, Thing, Tier, TierInput, TierResult, TraceNode, TypeRef, Use, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldPart };
3786
+ //#region src/providers.d.ts
3787
+ /** The type that a provider reads, and the problems of the reading. Each problem tells what the type does not test. */
3788
+ interface TypeReading {
3789
+ readonly type: ValueType;
3790
+ readonly issues: readonly TypeIssue[];
3791
+ }
3792
+ /**
3793
+ * This function makes a value type from a JSON Schema (TYPE.SCHEMA). A host uses it for the type of a root, for
3794
+ * example the schema of a store for `world`. It reads this subset:
3795
+ *
3796
+ * - `type`: `null`, `boolean`, `number`, `integer` (as `number`), `string`, `object` and `array`, or a list of them.
3797
+ * - `properties`, `required` and `additionalProperties` give a record. `false` closes it, and a property that is not
3798
+ * in `required` is optional.
3799
+ * - `items` gives a list. `enum` and `const` give `one`. `anyOf` and `oneOf` give a union.
3800
+ *
3801
+ * The type holds each value that the schema accepts. Each keyword that the function does not read tests nothing, as
3802
+ * `unknown`, and the issues name it. Examples are `minimum`, `pattern` and `allOf`. A schema with `$ref` or `nullable`
3803
+ * reads as `unknown`, because these keywords can permit more values. A schema with more than one of `type`, `anyOf`
3804
+ * and `oneOf` gives the type of the first, and an issue for each other. The function does not throw.
3805
+ *
3806
+ * @param schema - The schema, as JSON.
3807
+ * @returns The type, and the problems of the reading with their keys in the schema.
3808
+ */
3809
+ export declare function typeFromSchema(schema: unknown): TypeReading;
3810
+ /** The options of `typeFromSamples`. */
3811
+ interface SampleOptions {
3812
+ /** `true`: the samples show each field, thus each record type is closed. The default is `false`. */
3813
+ readonly closed?: boolean;
3814
+ }
3815
+ /**
3816
+ * This function infers a value type from sample values (TYPE.SAMPLES), as a type provider of F# does. A host uses it
3817
+ * for the type of a root, for example from some events.
3818
+ *
3819
+ * - `null`, a truth value, a number and a text give their base types, not their values.
3820
+ * - The items of each list join into one type of items.
3821
+ * - All records join into one record with each key of the samples. A key that a record does not have is optional.
3822
+ * - Values of different forms give a union, as `join` gives. No samples give `never`.
3823
+ * - A value without a type of the kernel, for example a function, gives `unknown`.
3824
+ *
3825
+ * Each sample is a member of the type. A record is open, because samples do not show that a field cannot exist. With
3826
+ * `closed: true`, each record is closed, and a reference to a field that no sample has gives `#TYPE!`.
3827
+ *
3828
+ * @param values - The sample values.
3829
+ * @param options - `closed: true` closes each record type.
3830
+ * @returns The type.
3831
+ */
3832
+ export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
3833
+ //#endregion
3834
+ export type { AgreeOptions, Agreement, Alias, AllOptions, Answer, AskOptions, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, DomainCodec, DomainExtension, Durable, DurableCounts, DurableOptions, Edge, Effect, EffectsOptions, Envelope, Epochs, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, FactsOptions, Failed, Finding, FormulaProfile, GenerateOptions, Give, GraphCycle, GraphEdge, GraphNode, GraphOptions, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindFacts, KindSource, LazyOp, LazyRule, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, NodeEdge, NodeGraph, NodeInfo, NodeRunOptions, Obligation, OpFn, OrderProblem, Outcome, ParseResult, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, PrepareOptions, Random, Read, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReplayEntry, ReplayLog, ReplayOptions, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleCounts, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepSpec, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxFixity, SyntaxForm, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldPart };
2318
3835
  //# sourceMappingURL=index.d.ts.map