@mark1russell7/coeval 0.21.0 → 0.23.0
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/README.md +23 -5
- package/build/index.d.ts +420 -116
- package/build/index.d.ts.map +1 -1
- package/build/index.js +5669 -3655
- package/build/index.js.map +1 -1
- package/package.json +4 -4
- package/src/codec-laws.ts +152 -0
- package/src/codec.ts +2 -2
- package/src/conform.ts +662 -70
- package/src/deref.ts +17 -3
- package/src/durable.ts +21 -9
- package/src/errors.ts +17 -1
- package/src/evaluate.ts +55 -21
- package/src/formula.ts +82 -22
- package/src/index.ts +16 -0
- package/src/instances.ts +61 -6
- package/src/meaning.ts +43 -10
- package/src/parts.ts +7 -4
- package/src/providers.ts +4 -1
- package/src/reference.ts +134 -9
- package/src/schedule.ts +286 -45
- package/src/static.ts +116 -23
- package/src/stdlib.ts +229 -6
- package/src/syntax.ts +430 -48
- package/src/types.ts +2 -1
- package/src/world.ts +106 -1
package/build/index.d.ts
CHANGED
|
@@ -337,7 +337,8 @@ interface Domain {
|
|
|
337
337
|
/**
|
|
338
338
|
* The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
|
|
339
339
|
* must be pure. `decode(encode(v))` must equal `v` by `sameValue` (EXT.ROUNDTRIP). The codec must give one JSON
|
|
340
|
-
* value for each member, thus the same value has the same document in each language (D12).
|
|
340
|
+
* value for each member, thus the same value has the same document in each language (D12). `codecLaws` examines
|
|
341
|
+
* these laws for the members of the domain (D130).
|
|
341
342
|
*/
|
|
342
343
|
interface DomainCodec {
|
|
343
344
|
/**
|
|
@@ -537,6 +538,15 @@ interface HostThing {
|
|
|
537
538
|
known?(key: Key): {
|
|
538
539
|
readonly thing: Thing;
|
|
539
540
|
} | undefined;
|
|
541
|
+
/**
|
|
542
|
+
* This optional function holds a kept read (SCHED.OWN-NODE). The evaluation did not ask for that read. Thus a host
|
|
543
|
+
* that follows the reads of an evaluation can tell the two apart. The kernel calls this function of the root `world`
|
|
544
|
+
* around each kept read that resolves its path.
|
|
545
|
+
*
|
|
546
|
+
* @param read - This function does the read.
|
|
547
|
+
* @returns What `read` gives.
|
|
548
|
+
*/
|
|
549
|
+
keeping?<T>(read: () => T): T;
|
|
540
550
|
}
|
|
541
551
|
/** Something that a path can reach: any value of the host, or a host thing. */
|
|
542
552
|
type Thing = unknown;
|
|
@@ -758,6 +768,44 @@ export declare function worldThing(world: World): Json;
|
|
|
758
768
|
* @returns The context.
|
|
759
769
|
*/
|
|
760
770
|
export declare function context(parts?: Partial<Context>): Context;
|
|
771
|
+
/**
|
|
772
|
+
* A compiled path: one static path for one navigator (PLAN.PATH). `compilePath` reads the root, the open roots and
|
|
773
|
+
* the steps one time. It asks the ladder of the verb `step` for each step document one time. Each resolution then
|
|
774
|
+
* examines only the values of the context. Code of a language reads a compiled path with `resolveCompiled`, thus the
|
|
775
|
+
* list of reads gets the read (PLAN.PATH-READS).
|
|
776
|
+
*/
|
|
777
|
+
interface CompiledPath {
|
|
778
|
+
/** The steps of the path, as the document gives them. The list of reads records these steps. */
|
|
779
|
+
readonly path: readonly unknown[];
|
|
780
|
+
/** The navigator of the compilation. A runtime with another navigator resolves the steps again. */
|
|
781
|
+
readonly nav: Navigator;
|
|
782
|
+
/**
|
|
783
|
+
* This function resolves the path from a context, without a record of hops. It records no read and it does not
|
|
784
|
+
* apply the grant of the evaluation, as `resolve` does not. Use it only outside an evaluation.
|
|
785
|
+
*
|
|
786
|
+
* @param ctx - The context.
|
|
787
|
+
* @returns The same resolution as `resolve(nav, ctx, path, { hops: false })`.
|
|
788
|
+
*/
|
|
789
|
+
resolve(ctx: Context): Resolution;
|
|
790
|
+
}
|
|
791
|
+
/**
|
|
792
|
+
* This function compiles one static path for one navigator. The resolver gives the same thing, error and reason as
|
|
793
|
+
* `resolve` without hops (PLAN.PATH-SAME). It keeps no value of a context.
|
|
794
|
+
*
|
|
795
|
+
* - Some paths take the full algorithm at once, because the short path cannot answer them. A path from `caps` or from
|
|
796
|
+
* a closed root is one. A path with a step document and each path of a navigator with `adopt` are others.
|
|
797
|
+
* - Each other path walks the short path from its root, and it takes the full algorithm when the values need it.
|
|
798
|
+
* - The walker of each step document comes from the ladder one time, here. The navigator and the step document do
|
|
799
|
+
* not change, thus the answer does not change either.
|
|
800
|
+
*
|
|
801
|
+
* An evaluator of a language calls this function in its `compile`, with the field `machine` of the input, and reads the
|
|
802
|
+
* result with `resolveCompiled` (PLAN.PATH-EXPORT).
|
|
803
|
+
*
|
|
804
|
+
* @param nav - The navigator. A plan compiles its paths for its machine.
|
|
805
|
+
* @param path - The steps. The first step is a root. The compiled path keeps this list, thus the host must not change it.
|
|
806
|
+
* @returns The compiled path.
|
|
807
|
+
*/
|
|
808
|
+
export declare function compilePath(nav: Navigator, path: readonly unknown[]): CompiledPath;
|
|
761
809
|
/**
|
|
762
810
|
* This function resolves a path from a context, and records each hop.
|
|
763
811
|
*
|
|
@@ -962,6 +1010,8 @@ interface KindFacts {
|
|
|
962
1010
|
* whose attributes each declare `circular` gives a fixed point.
|
|
963
1011
|
* - `collect`: the value of a node without an answer of the first four rungs and without a fold. The node combines
|
|
964
1012
|
* the contributions of each node of its subtree (TREE.COLLECT, D122).
|
|
1013
|
+
* - `higher`: the value of a node without an answer of the rungs before it. The term gives a document as data. The kit
|
|
1014
|
+
* evaluates that document with the node as `self`, thus its root is a new node under the node (TREE.HIGHER, D126).
|
|
965
1015
|
*/
|
|
966
1016
|
interface AttributeDeclaration {
|
|
967
1017
|
readonly copy?: boolean;
|
|
@@ -972,6 +1022,7 @@ interface AttributeDeclaration {
|
|
|
972
1022
|
readonly default?: Json;
|
|
973
1023
|
readonly circular?: CircularDeclaration;
|
|
974
1024
|
readonly collect?: CollectDeclaration;
|
|
1025
|
+
readonly higher?: Json;
|
|
975
1026
|
}
|
|
976
1027
|
/**
|
|
977
1028
|
* The declaration `collect` of an attribute (TREE.COLLECT, D122). The node of the attribute visits each node of its
|
|
@@ -1012,6 +1063,8 @@ interface CircularDeclaration {
|
|
|
1012
1063
|
readonly start: Json;
|
|
1013
1064
|
readonly limit?: number;
|
|
1014
1065
|
}
|
|
1066
|
+
/** The most generated documents on the way from a node to the root of its tree (TREE.HIGHER-DEPTH, D126). */
|
|
1067
|
+
export declare const GENERATION_LIMIT = 64;
|
|
1015
1068
|
/** The most rounds of a circular attribute without its own `limit` (TREE.CIRCULAR-LIMIT, D113). */
|
|
1016
1069
|
export declare const CIRCULAR_LIMIT = 100;
|
|
1017
1070
|
/** A declaration `circular` that the kit can use: its start value and its limit, or the reason of a bad declaration. */
|
|
@@ -1050,13 +1103,80 @@ export declare function collectOf(declared: unknown): CollectRule;
|
|
|
1050
1103
|
* - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
|
|
1051
1104
|
* - `contributes`: the contribution of the node to each collection of an attribute (TREE.COLLECT, D122). An
|
|
1052
1105
|
* equation sees no names.
|
|
1106
|
+
* - `at`: the attributes with parameters of the node (TREE.AT, D124). Only the step `tree.at` reads them, and the
|
|
1107
|
+
* equation sees each parameter as a name.
|
|
1108
|
+
* - `forwards`: the name of an attribute that gives a node. An attribute that no other rung answers comes from that
|
|
1109
|
+
* node (TREE.FORWARD, D126).
|
|
1053
1110
|
*/
|
|
1054
1111
|
interface TreeContract {
|
|
1055
1112
|
readonly equations?: Readonly<Record<string, Json>>;
|
|
1056
1113
|
readonly down?: Readonly<Record<string, Json>>;
|
|
1057
1114
|
readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
|
|
1058
1115
|
readonly contributes?: Readonly<Record<string, Json>>;
|
|
1116
|
+
readonly at?: Readonly<Record<string, AtEquation>>;
|
|
1117
|
+
readonly forwards?: string;
|
|
1059
1118
|
}
|
|
1119
|
+
/**
|
|
1120
|
+
* An attribute with parameters (TREE.AT, D124), as `paramAttr` in Kiama. The step `tree.at` gives the arguments. The
|
|
1121
|
+
* equation evaluates with the node as `self`, and it sees each parameter as a name, for example `names.width`.
|
|
1122
|
+
*/
|
|
1123
|
+
interface AtEquation {
|
|
1124
|
+
/** The names of the parameters. The step gives an argument for each of them, and no other argument. */
|
|
1125
|
+
readonly params: readonly string[];
|
|
1126
|
+
readonly equation: Json;
|
|
1127
|
+
}
|
|
1128
|
+
/** An entry of `tree.at` that the kit can use, or the reason of a bad entry (D124). */
|
|
1129
|
+
type AtRule = {
|
|
1130
|
+
readonly ok: true;
|
|
1131
|
+
readonly params: readonly string[];
|
|
1132
|
+
readonly equation: Json;
|
|
1133
|
+
} | {
|
|
1134
|
+
readonly ok: false;
|
|
1135
|
+
readonly reason: string;
|
|
1136
|
+
};
|
|
1137
|
+
/**
|
|
1138
|
+
* This function reads an entry of the table `tree.at` (D124). The tree kit, the reference, `check` and the graph of
|
|
1139
|
+
* attribute instances read it with this one function.
|
|
1140
|
+
*
|
|
1141
|
+
* @param declared - The entry.
|
|
1142
|
+
* @returns The rule, or the reason when the entry has no correct form.
|
|
1143
|
+
*/
|
|
1144
|
+
export declare function atRuleOf(declared: unknown): AtRule;
|
|
1145
|
+
/** The arguments of a step `tree.at` (D124): the names of the equation and their key, or the reason of bad arguments. */
|
|
1146
|
+
type AtArgs = {
|
|
1147
|
+
readonly ok: true;
|
|
1148
|
+
readonly names: Readonly<Record<string, Json>>;
|
|
1149
|
+
readonly key: string;
|
|
1150
|
+
} | {
|
|
1151
|
+
readonly ok: false;
|
|
1152
|
+
readonly reason: string;
|
|
1153
|
+
};
|
|
1154
|
+
/**
|
|
1155
|
+
* This function examines the arguments of a step `tree.at` (D124). The step gives an argument for each parameter, and
|
|
1156
|
+
* no other argument. Each argument is JSON data. The key is the text of `argsKey`, thus two equal arguments give one key.
|
|
1157
|
+
*
|
|
1158
|
+
* @param params - The parameters of the attribute.
|
|
1159
|
+
* @param args - The field `args` of the step.
|
|
1160
|
+
* @returns The names of the equation and the key, or the reason.
|
|
1161
|
+
*/
|
|
1162
|
+
export declare function atArgsOf(params: readonly string[], args: unknown): AtArgs;
|
|
1163
|
+
/**
|
|
1164
|
+
* This function gives the key of a JSON value (D124). The fields of a record are in the order of their names. Two
|
|
1165
|
+
* values have the same key only when they are equal by DOC.EQUALS, thus `-0` and `0` have different keys.
|
|
1166
|
+
*
|
|
1167
|
+
* @param value - The value.
|
|
1168
|
+
* @returns The JSON text, or `undefined` for a value that is not JSON data: a number that is not finite, a host value or a cycle.
|
|
1169
|
+
*/
|
|
1170
|
+
export declare function argsKey(value: unknown): string | undefined;
|
|
1171
|
+
/**
|
|
1172
|
+
* This function gives the structural key of a document (TREE.HIGHER-PLAN, D126). The fields of a record keep their
|
|
1173
|
+
* order, because the order of the parts decides the order of the JSON and the first error. Thus one key means one
|
|
1174
|
+
* document, and the two documents are equal by DOC.EQUALS.
|
|
1175
|
+
*
|
|
1176
|
+
* @param doc - The document.
|
|
1177
|
+
* @returns The JSON text, or `undefined` for a value that is not JSON data.
|
|
1178
|
+
*/
|
|
1179
|
+
export declare function documentKey(doc: unknown): string | undefined;
|
|
1060
1180
|
/**
|
|
1061
1181
|
* This function gives the type of a bare equation of a kind (D42). It is the type `of` of the shape of its parts, or
|
|
1062
1182
|
* else the type `of` of the shape `rest` of a record. The plan, the reference and `check` read it with this one function.
|
|
@@ -2426,6 +2546,18 @@ interface EvaluateOptions {
|
|
|
2426
2546
|
/** A list that gets each read, in the order of the resolutions (READS.RECORD). */
|
|
2427
2547
|
readonly reads?: Read[];
|
|
2428
2548
|
}
|
|
2549
|
+
/**
|
|
2550
|
+
* This function resolves a compiled path through a runtime (PLAN.PATH). The runtime of the kernel uses the compiled
|
|
2551
|
+
* path. Each other runtime gets the steps through `resolve`, thus a runtime that wraps another runtime sees each path
|
|
2552
|
+
* (PLAN.PATH-ROUTE). The result and the list of reads are the same as for `rt.resolve(ctx, compiled.path)`
|
|
2553
|
+
* (PLAN.PATH-READS).
|
|
2554
|
+
*
|
|
2555
|
+
* @param rt - The runtime.
|
|
2556
|
+
* @param ctx - The context.
|
|
2557
|
+
* @param compiled - The compiled path, from `compilePath`.
|
|
2558
|
+
* @returns What the path reached, or an error.
|
|
2559
|
+
*/
|
|
2560
|
+
export declare function resolveCompiled(rt: Runtime, ctx: Context, compiled: CompiledPath): Resolution;
|
|
2429
2561
|
/** The options of a compilation. */
|
|
2430
2562
|
interface PrepareOptions {
|
|
2431
2563
|
/** The type of a bare root value. */
|
|
@@ -3036,6 +3168,21 @@ interface SyntaxHeader {
|
|
|
3036
3168
|
*/
|
|
3037
3169
|
readonly bind?: string;
|
|
3038
3170
|
}
|
|
3171
|
+
/**
|
|
3172
|
+
* The text forms of the constructs of the formula kit (K145, D127). Each field is the kind of one form, with dots
|
|
3173
|
+
* between the keys. A construct without a field has no text. Each text of a form was an issue before, and no form
|
|
3174
|
+
* reserves a name.
|
|
3175
|
+
*/
|
|
3176
|
+
interface SyntaxConstructs {
|
|
3177
|
+
/** The kind of the form `{a: 1, b: x}`. Its value is a record of documents. */
|
|
3178
|
+
readonly record?: string;
|
|
3179
|
+
/** The kind of the form `let {a: 1} in a + 1`. Its value has the fields `bind` and `body`. */
|
|
3180
|
+
readonly let?: string;
|
|
3181
|
+
/** The kind of the form `(x, y) => x + y`. Its value has the fields `params` and `body`. */
|
|
3182
|
+
readonly fn?: string;
|
|
3183
|
+
/** The kind of the form `(f)(1, 2)`: a call of a value. Its value has the fields `fn` and `args`. */
|
|
3184
|
+
readonly call?: string;
|
|
3185
|
+
}
|
|
3039
3186
|
/**
|
|
3040
3187
|
* The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
|
|
3041
3188
|
* reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
|
|
@@ -3052,6 +3199,8 @@ interface SyntaxProfile {
|
|
|
3052
3199
|
readonly calls?: SyntaxCalls;
|
|
3053
3200
|
/** The text of the header of a document. */
|
|
3054
3201
|
readonly header?: SyntaxHeader;
|
|
3202
|
+
/** The text forms of the constructs. Without a field, the construct has no text. */
|
|
3203
|
+
readonly constructs?: SyntaxConstructs;
|
|
3055
3204
|
/** The deepest nesting that `parse` accepts. The default is `256`. */
|
|
3056
3205
|
readonly maxDepth?: number;
|
|
3057
3206
|
}
|
|
@@ -3064,7 +3213,12 @@ interface SyntaxIssue {
|
|
|
3064
3213
|
/** The message. */
|
|
3065
3214
|
readonly message: string;
|
|
3066
3215
|
}
|
|
3067
|
-
/**
|
|
3216
|
+
/**
|
|
3217
|
+
* The most issues that `parse` gives for one text (D138). A person reads a list of this size, and a text with more
|
|
3218
|
+
* issues needs another kind of help.
|
|
3219
|
+
*/
|
|
3220
|
+
export declare const MAX_SYNTAX_ISSUES = 20;
|
|
3221
|
+
/** The result of `parse`: a document, or the problems of the text in the order of their offsets (D138). */
|
|
3068
3222
|
type ParseResult = {
|
|
3069
3223
|
readonly ok: true;
|
|
3070
3224
|
readonly doc: Json;
|
|
@@ -3076,12 +3230,14 @@ type ParseResult = {
|
|
|
3076
3230
|
* The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
|
|
3077
3231
|
* `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
|
|
3078
3232
|
* `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs. The
|
|
3079
|
-
* text `total = 2 + 3` gives the document the header name `total` (D62).
|
|
3233
|
+
* text `total = 2 + 3` gives the document the header name `total` (D62). The forms `{a: 1}`, `let {a: 1} in a`,
|
|
3234
|
+
* `(x) => x` and `(f)(1)` make `record`, `let`, `fn` and `call` (D127).
|
|
3080
3235
|
*/
|
|
3081
3236
|
export declare const STD_SYNTAX: SyntaxProfile;
|
|
3082
3237
|
/**
|
|
3083
3238
|
* This function reads a text into a document with the rules of a profile (SYNTAX.PARSE). It does not throw for a
|
|
3084
|
-
* bad text.
|
|
3239
|
+
* bad text. Each issue gives the offset, the length and a message (SYNTAX.SPAN). The field `issues` gives at most
|
|
3240
|
+
* `MAX_SYNTAX_ISSUES` issues (SYNTAX.ISSUES-ALL). A host that reads the first issue reads the first fault of the text.
|
|
3085
3241
|
*
|
|
3086
3242
|
* @param profile - The syntax profile.
|
|
3087
3243
|
* @param text - The text.
|
|
@@ -3130,7 +3286,7 @@ export declare const WORLD_SYNTAX: SyntaxProfile;
|
|
|
3130
3286
|
/** The code of the evaluators of the standard world, by name. */
|
|
3131
3287
|
export declare const STD_EVALUATORS: Readonly<Record<string, Evaluator>>;
|
|
3132
3288
|
/** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
|
|
3133
|
-
type AttributeRung = "own" | "kind" | "parent" | "copy" | "default";
|
|
3289
|
+
type AttributeRung = "own" | "kind" | "parent" | "copy" | "default" | "forward";
|
|
3134
3290
|
/** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
|
|
3135
3291
|
export declare const ATTRIBUTE_RUNGS: readonly AttributeRung[];
|
|
3136
3292
|
/** The record of the demand of one attribute of a node (TREE.RUNGS). */
|
|
@@ -3159,6 +3315,10 @@ interface AttributeAnswer {
|
|
|
3159
3315
|
* A new plan gives new arrays. Thus a host keeps its cells by the identity of `place` and by `attribute`.
|
|
3160
3316
|
* A host that keeps its cells by the keys of `place` can give the answer of another node or a stale answer.
|
|
3161
3317
|
*
|
|
3318
|
+
* An attribute with parameters gets one cell for each key of its arguments (TREE.AT-CELL, D124). Its `place` is a
|
|
3319
|
+
* second array with the same keys, one for each key of a node. Its `attribute` is the JSON text of the name and the
|
|
3320
|
+
* arguments, for example `["height",{"width":200}]`.
|
|
3321
|
+
*
|
|
3162
3322
|
* The function gives the answer of `compute`, or a kept answer. A host with signals gives a computed signal: a change
|
|
3163
3323
|
* of its store then makes only the attributes that read the store compute again. Each demand gives a new `compute`, and
|
|
3164
3324
|
* a cell that computes again uses the last one.
|
|
@@ -3597,6 +3757,65 @@ export declare function encodeValue(machine: Pick<Machine, "domains">, value: un
|
|
|
3597
3757
|
* @returns The value, or the error of the evaluation.
|
|
3598
3758
|
*/
|
|
3599
3759
|
export declare function decodeValue(machine: Machine, doc: unknown): Result;
|
|
3760
|
+
/**
|
|
3761
|
+
* A law of a codec that `codecLaws` checks.
|
|
3762
|
+
*
|
|
3763
|
+
* - `samples`: the check has at least one member of the domain. Without a member, the check proves nothing.
|
|
3764
|
+
* - `encode`: `encode` writes each member, and it does not throw.
|
|
3765
|
+
* - `json`: the data of `encode` is JSON. `JSON.parse(JSON.stringify(data))` gives equal data, thus the data has no
|
|
3766
|
+
* `NaN`, no `-0`, no infinity, no `undefined`, no function, no host object and no cycle.
|
|
3767
|
+
* - `stable`: the same member has one document. A second `encode` of the member gives equal data, and so does an
|
|
3768
|
+
* `encode` of the decoded member. The check compares with `docEquals`.
|
|
3769
|
+
* - `decode`: `decodeDomain` reads the JSON copy of the data, and it gives a member of the domain.
|
|
3770
|
+
* - `roundtrip`: the decoded member equals the member by `sameValue`.
|
|
3771
|
+
*/
|
|
3772
|
+
type CodecLaw = "samples" | "encode" | "json" | "stable" | "decode" | "roundtrip";
|
|
3773
|
+
/** The probe of a finding of `codecLaws`: the domain, the member and the data of the member. */
|
|
3774
|
+
interface CodecProbe {
|
|
3775
|
+
/** The name of the domain. */
|
|
3776
|
+
readonly domain: string;
|
|
3777
|
+
/** The member that shows the finding. The law `samples` has no member, thus the value is `undefined`. */
|
|
3778
|
+
readonly value: unknown;
|
|
3779
|
+
/** The data that `encode` gave for the member. The laws `samples` and `encode` have no data. */
|
|
3780
|
+
readonly data?: unknown;
|
|
3781
|
+
}
|
|
3782
|
+
/** One law that a codec breaks, with the reason and the first probe that shows it. The form is the form of `Finding`. */
|
|
3783
|
+
interface CodecFinding {
|
|
3784
|
+
readonly obligation: CodecLaw;
|
|
3785
|
+
/** One sentence that tells what the codec did. */
|
|
3786
|
+
readonly reason: string;
|
|
3787
|
+
readonly probe: CodecProbe;
|
|
3788
|
+
}
|
|
3789
|
+
/** The options of `codecLaws`. */
|
|
3790
|
+
interface CodecLawsOptions {
|
|
3791
|
+
/** More members of the domain. They come first. A value that is not a member of the domain gets no test. */
|
|
3792
|
+
readonly samples?: readonly unknown[];
|
|
3793
|
+
/**
|
|
3794
|
+
* This function compares two values that the rules of `sameValue` do not know, as in `agree`. A member that is an
|
|
3795
|
+
* object needs this rule, for example a date, because `sameValue` compares an object only with itself.
|
|
3796
|
+
*
|
|
3797
|
+
* @param a - The first value.
|
|
3798
|
+
* @param b - The second value.
|
|
3799
|
+
* @returns `true` or `false`, or `undefined` for the rules of `sameValue`.
|
|
3800
|
+
*/
|
|
3801
|
+
readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
|
|
3802
|
+
}
|
|
3803
|
+
/**
|
|
3804
|
+
* This function examines the laws of the codec of one domain of a machine (K141, D130). A test of a language starts it
|
|
3805
|
+
* for each domain with a codec. The members are the list `values` of the domain, or else the given samples, the edge
|
|
3806
|
+
* values and the lists `samples` of the domains. Each value that is not a member gets no test.
|
|
3807
|
+
*
|
|
3808
|
+
* The law `decode` reads the JSON copy of the data through `decodeDomain`, as an evaluation of `ext.domain` does. Thus
|
|
3809
|
+
* a codec that reads a data object by its identity breaks a law. The finding of a law names the first member that
|
|
3810
|
+
* breaks it. An empty list means that each member keeps each law.
|
|
3811
|
+
*
|
|
3812
|
+
* @param machine - The machine, or only its domains.
|
|
3813
|
+
* @param name - The name of the domain.
|
|
3814
|
+
* @param options - The samples and the rule of equality.
|
|
3815
|
+
* @returns The first finding of each law that the codec breaks, in the order of the laws.
|
|
3816
|
+
* @throws {Error} The machine has no domain with the name, or the domain has no codec.
|
|
3817
|
+
*/
|
|
3818
|
+
export declare function codecLaws(machine: Pick<Machine, "domains">, name: string, options?: CodecLawsOptions): readonly CodecFinding[];
|
|
3600
3819
|
/**
|
|
3601
3820
|
* The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
|
|
3602
3821
|
* compiled evaluator or runner of a machine needs a definition here. A function evaluator needs none.
|
|
@@ -3854,12 +4073,20 @@ export declare function agreeRun(machine: Machine, doc: unknown, context?: Conte
|
|
|
3854
4073
|
* - `C8`: compiled code gives the result of code that compiles again at the time of the evaluation.
|
|
3855
4074
|
* - `local`: the code keeps no state from one call to the next.
|
|
3856
4075
|
* - `agree`: compiled code gives the result of its definition for the reference interpreter.
|
|
4076
|
+
* - `parallel`: the code gives the same result, the same parts and the same effects in each order of the waits of
|
|
4077
|
+
* `all` (D128). Only a runner gets this check.
|
|
3857
4078
|
* - `truth`: the own `truthy` of a formula profile gives `true` or `false` for each member of its `truthType` (D86).
|
|
3858
4079
|
* Only `formula.if`, `formula.and` and `formula.or` of the formula kit get this check.
|
|
3859
4080
|
* - `cover`: each sample of a covered domain of the machine is in one domain of each cover of the domain (D94). Each
|
|
3860
4081
|
* evaluator and each runner gets this check, because `fits` trusts the covers for each program.
|
|
3861
|
-
|
|
3862
|
-
|
|
4082
|
+
* - `result`: a walker, the code of a `deref` or a function of a profile gives the form that its type states. A walker
|
|
4083
|
+
* and the code of a `deref` throw nothing, except a `Failure` (D137).
|
|
4084
|
+
* - `ladder`: a walker steps on a host thing only through `deref` and `has` of its input (D137).
|
|
4085
|
+
* - `hops`: each `visit` of a walker tells a step that the walk followed. Without `visit`, the walk stays the same (D137).
|
|
4086
|
+
* - `has`: the function `has` of the code of a `deref` gives a truth, and `true` for each key that the code answers (D137).
|
|
4087
|
+
* - `typed`: a walker keeps its type rule, an operation its signatures and an extension its entry in `extTypes` (D137).
|
|
4088
|
+
*/
|
|
4089
|
+
type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree" | "parallel" | "truth" | "cover" | "result" | "ladder" | "hops" | "has" | "typed";
|
|
3863
4090
|
/** The probe of a finding: the document, the result of each probe part, the capabilities and the handler. */
|
|
3864
4091
|
interface ConformProbe {
|
|
3865
4092
|
/** The text of the type of the document. */
|
|
@@ -3874,6 +4101,10 @@ interface ConformProbe {
|
|
|
3874
4101
|
readonly caps: readonly Cap[];
|
|
3875
4102
|
/** `true` in a run, in which the host does each effect and a part can wait. */
|
|
3876
4103
|
readonly running: boolean;
|
|
4104
|
+
/** The thing before the step, in a finding of a walker. */
|
|
4105
|
+
readonly here?: unknown;
|
|
4106
|
+
/** The key of the step, in a finding of the code of a `deref`. */
|
|
4107
|
+
readonly key?: Key;
|
|
3877
4108
|
}
|
|
3878
4109
|
/** One obligation that the code breaks, with the reason and the first probe that shows it. */
|
|
3879
4110
|
interface Finding {
|
|
@@ -3888,6 +4119,9 @@ interface ConformOptions {
|
|
|
3888
4119
|
* The verb that the evaluator serves. The default is `eval`. The facts `pure` and `lazy` of a contract describe only
|
|
3889
4120
|
* `eval`, thus `conforms` checks C3 and C4 only for `eval` (D23). `conforms` checks C2 for each verb that the
|
|
3890
4121
|
* contract declares effects for: `eval`, and each verb with an entry in `verbEffects` (D49).
|
|
4122
|
+
*
|
|
4123
|
+
* The verb `step` selects the walker of the name, and the verb `deref` selects the code of the `deref` of the name
|
|
4124
|
+
* (D137). Without the option, a name that no evaluator and no runner has selects its walker, and then its `deref`.
|
|
3891
4125
|
*/
|
|
3892
4126
|
readonly verb?: string;
|
|
3893
4127
|
/**
|
|
@@ -3910,11 +4144,16 @@ interface ConformOptions {
|
|
|
3910
4144
|
* definition from `STD_DEFINITIONS`.
|
|
3911
4145
|
*/
|
|
3912
4146
|
readonly definitions?: Definitions;
|
|
4147
|
+
/**
|
|
4148
|
+
* More things before the step of a walker (D137). Use them for the things that a walker needs, for example a host
|
|
4149
|
+
* thing of the language. The default holds three probe nodes, a document, `undefined` and the values of the results.
|
|
4150
|
+
*/
|
|
4151
|
+
readonly things?: readonly unknown[];
|
|
3913
4152
|
/** The capabilities of half of the probes. The other half has none. The default is the declared effects and `probe`. */
|
|
3914
4153
|
readonly caps?: readonly Cap[];
|
|
3915
4154
|
/** The names of the context of each probe. */
|
|
3916
4155
|
readonly names?: Readonly<Record<string, unknown>>;
|
|
3917
|
-
/** The seed of the random results
|
|
4156
|
+
/** The seed of the random results and of the orders of `all`. The same seed gives the same probes. The default is 1. */
|
|
3918
4157
|
readonly seed?: number;
|
|
3919
4158
|
/** The count of probes with random results for each probe document. The default is 12. */
|
|
3920
4159
|
readonly runs?: number;
|
|
@@ -3939,11 +4178,18 @@ interface ConformOptions {
|
|
|
3939
4178
|
* compiled code with its definition. The finding of an obligation names the first probe that breaks it. An empty list
|
|
3940
4179
|
* means that each probe conforms.
|
|
3941
4180
|
*
|
|
4181
|
+
* The check `parallel` starts a runner with a choice of waits under `all` again, in other orders of the waits (D128).
|
|
3942
4182
|
* The check `truth` tests the declared truth of a formula profile (D86). The check `cover` tests the covers of the
|
|
3943
4183
|
* domains of the machine from samples (D94).
|
|
3944
4184
|
*
|
|
4185
|
+
* The name can also select a walker or the code of a `deref` (D137). The checks of a walker are `result`, `local`,
|
|
4186
|
+
* `ladder`, `hops`, `typed` and `C4`. The checks of the code of a `deref` are `result`, `local` and `has`. The evaluators
|
|
4187
|
+
* `formula.op` and `formula.ext` also examine each operation and each extension that the tables of their profile list.
|
|
4188
|
+
* The checks `typed` and `result` test the functions of the profile directly.
|
|
4189
|
+
*
|
|
3945
4190
|
* @param machine - The machine with the code and the world of the kinds.
|
|
3946
|
-
* @param name - The name of the
|
|
4191
|
+
* @param name - The name of the code. A runner wins over an evaluator of the same name, and each of them wins over a
|
|
4192
|
+
* walker or a `deref` without the option `verb`.
|
|
3947
4193
|
* @param options - The verb, the types and the values of the probe documents, and the results of the probe parts. Also
|
|
3948
4194
|
* the definitions, the capabilities, the names, the seed, the mock and the rule of equality.
|
|
3949
4195
|
* @returns The first finding of each obligation that the code breaks, in the order of the obligations.
|
|
@@ -4188,6 +4434,105 @@ interface Durable {
|
|
|
4188
4434
|
* @returns The cache.
|
|
4189
4435
|
*/
|
|
4190
4436
|
export declare function durable(machine: Machine, options?: DurableOptions): Durable;
|
|
4437
|
+
/** One edge of a graph of nodes: a read of a node by another node. `NodeEdge` of a schedule is such an edge. */
|
|
4438
|
+
interface GraphEdge<Id> {
|
|
4439
|
+
/** The node that the read reaches. It is `undefined` when the read can reach each node (GRAPH.UNKNOWN). */
|
|
4440
|
+
readonly to: Id | undefined;
|
|
4441
|
+
/** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
|
|
4442
|
+
readonly lazy: boolean;
|
|
4443
|
+
}
|
|
4444
|
+
/** One node of a graph, with its edges. `NodeInfo` of a schedule is such a node. */
|
|
4445
|
+
interface GraphNode<Id> {
|
|
4446
|
+
/** The edges to the nodes that the node reads. */
|
|
4447
|
+
readonly edges: readonly GraphEdge<Id>[];
|
|
4448
|
+
/** The side of the node. A node on the run side is a sink: no edge reaches it (SCHED.SIDE). The default is `derive`. */
|
|
4449
|
+
readonly side?: Side;
|
|
4450
|
+
}
|
|
4451
|
+
/**
|
|
4452
|
+
* A graph of nodes, by name. The order of the map is the order of the nodes in each answer. The function `graph` of
|
|
4453
|
+
* 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
|
|
4454
|
+
* analysis.
|
|
4455
|
+
*/
|
|
4456
|
+
type NodeGraph<Id> = ReadonlyMap<Id, GraphNode<Id>>;
|
|
4457
|
+
/** The options of an analysis. */
|
|
4458
|
+
interface GraphOptions {
|
|
4459
|
+
/**
|
|
4460
|
+
* `true`: the analysis keeps only the eager edges with a target node. Such a read occurs in each evaluation in
|
|
4461
|
+
* which each document around it gives a value (FACTS.LAZY). The default keeps each edge.
|
|
4462
|
+
*/
|
|
4463
|
+
readonly eager?: boolean;
|
|
4464
|
+
}
|
|
4465
|
+
/** One static cycle of a graph (GRAPH.CYCLE). */
|
|
4466
|
+
interface GraphCycle<Id> {
|
|
4467
|
+
/** The nodes of the cycle, in the order of the graph. */
|
|
4468
|
+
readonly nodes: readonly Id[];
|
|
4469
|
+
/**
|
|
4470
|
+
* `true` when the eager edges with a target close the cycle. `false` when the cycle needs a lazy edge or an edge
|
|
4471
|
+
* without a target. The value of each node still comes from the demand (D31).
|
|
4472
|
+
*/
|
|
4473
|
+
readonly certain: boolean;
|
|
4474
|
+
}
|
|
4475
|
+
/**
|
|
4476
|
+
* This function gives the strongly connected components of a graph of nodes (GRAPH.SCC), with the algorithm of
|
|
4477
|
+
* Tarjan. It keeps its own stack, thus a chain of 100000 nodes does not overflow the stack of the host.
|
|
4478
|
+
*
|
|
4479
|
+
* - Each component comes after each component that it reads: the deepest component comes first.
|
|
4480
|
+
* - A node that is on no cycle is a component of one node.
|
|
4481
|
+
* - The nodes of a component are in the order of the graph.
|
|
4482
|
+
*
|
|
4483
|
+
* @param graph - The nodes, each with its edges.
|
|
4484
|
+
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4485
|
+
* @returns The components, deepest first.
|
|
4486
|
+
*/
|
|
4487
|
+
export declare function components<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
|
|
4488
|
+
/**
|
|
4489
|
+
* This function gives the height of each node: the order of a push schedule (GRAPH.ORDER). A schedule that evaluates
|
|
4490
|
+
* the nodes from the lowest height up evaluates each node after each node that it reads, except on a cycle.
|
|
4491
|
+
*
|
|
4492
|
+
* - A node that reads no node outside its component has the height 0.
|
|
4493
|
+
* - Each other node is one higher than the highest node that it reads outside its component.
|
|
4494
|
+
* - The nodes of one component have one height.
|
|
4495
|
+
* - An edge without a target reads each node that is not a sink (GRAPH.UNKNOWN).
|
|
4496
|
+
*
|
|
4497
|
+
* @param graph - The nodes, each with its edges.
|
|
4498
|
+
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4499
|
+
* @returns The height of each node, in the order of the graph.
|
|
4500
|
+
*/
|
|
4501
|
+
export declare function heights<Id>(graph: NodeGraph<Id>, options?: GraphOptions): ReadonlyMap<Id, number>;
|
|
4502
|
+
/**
|
|
4503
|
+
* This function puts the nodes in layers by their heights, in linear time (GRAPH.LAYERS). The first layer has the
|
|
4504
|
+
* height 0. Two nodes of one layer read each other only inside one component. Thus a push schedule can evaluate the
|
|
4505
|
+
* components of one layer at the same time.
|
|
4506
|
+
*
|
|
4507
|
+
* @param graph - The nodes, each with its edges.
|
|
4508
|
+
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4509
|
+
* @returns The layers, from the height 0 up. Each layer keeps the order of the graph.
|
|
4510
|
+
*/
|
|
4511
|
+
export declare function nodeLayers<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
|
|
4512
|
+
/**
|
|
4513
|
+
* This function gives the nodes that a set of observed nodes needs (GRAPH.NECESSARY). These are the observed nodes,
|
|
4514
|
+
* and each node with a path of edges from them. A push schedule evaluates only these nodes. An observed name that is
|
|
4515
|
+
* not a node of the graph adds nothing.
|
|
4516
|
+
*
|
|
4517
|
+
* @param graph - The nodes, each with its edges.
|
|
4518
|
+
* @param observed - The nodes that the host shows or reads.
|
|
4519
|
+
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4520
|
+
* @returns The necessary nodes, in the order of the graph.
|
|
4521
|
+
*/
|
|
4522
|
+
export declare function necessary<Id>(graph: NodeGraph<Id>, observed: Iterable<Id>, options?: GraphOptions): ReadonlySet<Id>;
|
|
4523
|
+
/**
|
|
4524
|
+
* This function gives the static cycles of a graph (GRAPH.CYCLE): each component with two or more nodes, and each
|
|
4525
|
+
* node with an edge to itself. A cycle of the eager edges with a target is certain, and `check` or a host can report
|
|
4526
|
+
* it before a run. Another cycle is possible: an evaluation can skip a lazy read.
|
|
4527
|
+
*
|
|
4528
|
+
* - A component of all the edges that is also a component of the eager edges is one certain cycle.
|
|
4529
|
+
* - Each other component of all the edges is one possible cycle, and each certain cycle in it comes after it.
|
|
4530
|
+
* - A read can still fail before it occurs. Thus the demand of D31, not a static cycle, gives the value of each node.
|
|
4531
|
+
*
|
|
4532
|
+
* @param graph - The nodes, each with its edges.
|
|
4533
|
+
* @returns The cycles, deepest first.
|
|
4534
|
+
*/
|
|
4535
|
+
export declare function cycles<Id>(graph: NodeGraph<Id>): readonly GraphCycle<Id>[];
|
|
4191
4536
|
/** One edge of a graph of nodes: a static read of a node from the document of another node (SCHED.EDGES). */
|
|
4192
4537
|
interface NodeEdge {
|
|
4193
4538
|
/**
|
|
@@ -4219,6 +4564,17 @@ interface NodeInfo {
|
|
|
4219
4564
|
interface ScheduleOptions extends DurableOptions {
|
|
4220
4565
|
/** The context of the host: the names, `self`, `event` and the capabilities. The schedule sets the root `world` to the nodes. */
|
|
4221
4566
|
readonly context?: Context;
|
|
4567
|
+
/**
|
|
4568
|
+
* This function gives a node its own `self` (SCHED.NODE-CONTEXT, D135). Thus one document at each cell of a grid
|
|
4569
|
+
* shares one plan, and each cell has its own value and its own reads. In one data epoch, the function gives the same
|
|
4570
|
+
* data for a node. New data comes with `changeData`, and each node then verifies its reads with its new `self`.
|
|
4571
|
+
* Without the function, each node gets the context of the host.
|
|
4572
|
+
*
|
|
4573
|
+
* @param id - The name of the node.
|
|
4574
|
+
* @param host - The context of the host, without the nodes at the root `world`.
|
|
4575
|
+
* @returns The `self` of the node, or `undefined` for the `self` of the host.
|
|
4576
|
+
*/
|
|
4577
|
+
readonly selfOf?: (id: string, host: Context) => Thing;
|
|
4222
4578
|
}
|
|
4223
4579
|
/** The work of a schedule since its start: the work of its `durable` cache, and the demands ahead of a node. */
|
|
4224
4580
|
interface ScheduleCounts extends DurableCounts {
|
|
@@ -4246,7 +4602,7 @@ interface Schedule {
|
|
|
4246
4602
|
readonly epochs: Epochs;
|
|
4247
4603
|
/** The work of the schedule since its start: the compilations, the evaluations, the verifications, the reuses and the demands ahead. */
|
|
4248
4604
|
readonly counts: ScheduleCounts;
|
|
4249
|
-
/** The context of
|
|
4605
|
+
/** The context of the current data epoch: the context of the host, with the nodes at the root `world`. The option `selfOf` changes only the `self` of a node. */
|
|
4250
4606
|
readonly context: Context;
|
|
4251
4607
|
/**
|
|
4252
4608
|
* This function gives each node with its facts, its side and its edges (SCHED.GRAPH). The map stays the same object
|
|
@@ -4261,7 +4617,7 @@ interface Schedule {
|
|
|
4261
4617
|
*
|
|
4262
4618
|
* - First, the schedule demands each node that the eager edges reach, deepest first (SCHED.LONG-CHAIN).
|
|
4263
4619
|
* - After a change, a pure node verifies its reads, and it keeps its result when each read is the same (SCHED.STALE).
|
|
4264
|
-
* - Each node of a cycle gives `#CYCLE!`, in each order of demands (SCHED.CYCLE).
|
|
4620
|
+
* - Each node of a cycle gives `#CYCLE!`, in each order of demands (SCHED.CYCLE), at each length (SCHED.DEEP-CYCLE).
|
|
4265
4621
|
* - A node on the run side gives `#REF!`, because the schedule does not evaluate it (SCHED.SIDE).
|
|
4266
4622
|
*
|
|
4267
4623
|
* @param id - The name of the node.
|
|
@@ -4285,7 +4641,8 @@ interface Schedule {
|
|
|
4285
4641
|
remove(id: string): boolean;
|
|
4286
4642
|
/**
|
|
4287
4643
|
* This function tells the schedule that the data of the host changed (DURABLE.EPOCHS). The values of a context do
|
|
4288
|
-
* not change in place, thus new data comes in a new context, or through a host thing.
|
|
4644
|
+
* not change in place, thus new data comes in a new context, or through a host thing. A new `self` of a node is a
|
|
4645
|
+
* change of data too (SCHED.NODE-STALE).
|
|
4289
4646
|
*
|
|
4290
4647
|
* @param context - The new context of the host, or `undefined` to keep the context.
|
|
4291
4648
|
*/
|
|
@@ -4298,7 +4655,8 @@ interface Schedule {
|
|
|
4298
4655
|
changeMachine(machine: Machine): void;
|
|
4299
4656
|
/**
|
|
4300
4657
|
* This function starts a run of the document of a node, and the host does each effect (SCHED.RUN). Only the host
|
|
4301
|
-
* starts a run, for example at an event. A change of data does not start or repeat a run (L3).
|
|
4658
|
+
* starts a run, for example at an event. A change of data does not start or repeat a run (L3). The run gets the
|
|
4659
|
+
* `self` of its node (SCHED.NODE-CONTEXT).
|
|
4302
4660
|
*
|
|
4303
4661
|
* @param id - The name of the node.
|
|
4304
4662
|
* @param options - The event, the host code that does the effects, and a signal to stop the run.
|
|
@@ -4318,6 +4676,32 @@ interface Schedule {
|
|
|
4318
4676
|
* @returns The edges, in the order of the reads.
|
|
4319
4677
|
*/
|
|
4320
4678
|
export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
|
|
4679
|
+
/**
|
|
4680
|
+
* One certain cycle of a schedule, in the form of an issue of `check` (SCHED.CYCLE-ISSUES). The first node of `nodes`
|
|
4681
|
+
* gives the place and the reason. The place is the key of that node under the root `world`, and the reason has the
|
|
4682
|
+
* text of `#CYCLE!` for that node.
|
|
4683
|
+
*/
|
|
4684
|
+
interface CycleIssue extends Issue {
|
|
4685
|
+
readonly code: "#CYCLE!";
|
|
4686
|
+
/** The nodes of the cycle, sorted by name as the record of the root `world` sorts them. */
|
|
4687
|
+
readonly nodes: readonly string[];
|
|
4688
|
+
}
|
|
4689
|
+
/**
|
|
4690
|
+
* This function gives the certain cycles of a schedule before a run (SCHED.CYCLE-ISSUES, D131). It reads only `graph()`,
|
|
4691
|
+
* thus it evaluates no node. A host calls it when it needs the answer. A run does not call it.
|
|
4692
|
+
*
|
|
4693
|
+
* - Each certain cycle of `cycles` gives one issue. The issue has the place `[id]` of its first node.
|
|
4694
|
+
* - A possible cycle gives no issue, because a run can skip its lazy read (SCHED.CYCLE-CERTAIN).
|
|
4695
|
+
* - The order of the `set` calls does not change the answer (SCHED.CYCLE-ORDER).
|
|
4696
|
+
* - No node of an issue gives a value. A read can fail before it reaches the cycle, and the node then gives that
|
|
4697
|
+
* error (SCHED.CYCLE-AGREES). Thus the demand of D33 still gives the result of each node.
|
|
4698
|
+
*
|
|
4699
|
+
* @param target - The schedule, or another object that gives a graph of nodes.
|
|
4700
|
+
* @returns One issue for each certain cycle, sorted by the first node of each issue.
|
|
4701
|
+
*/
|
|
4702
|
+
export declare function checkCycles(target: {
|
|
4703
|
+
graph(): NodeGraph<string>;
|
|
4704
|
+
}): readonly CycleIssue[];
|
|
4321
4705
|
/**
|
|
4322
4706
|
* This function makes the demand schedule of a graph of named nodes (S1, R4, D31). A host gives each node a name and
|
|
4323
4707
|
* a document. The root `world` of each node reaches the other nodes by name. The context of the host gives the other
|
|
@@ -4333,12 +4717,16 @@ export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
|
|
|
4333
4717
|
* - A demand of the host, or of a run, first demands each node that the eager edges reach, deepest first. Thus each
|
|
4334
4718
|
* read of such a node finds a value, and a chain of 100000 nodes does not overflow the stack (SCHED.LONG-CHAIN).
|
|
4335
4719
|
* Each such demand starts with no node in evaluation, thus the order of demands keeps the values of D31.
|
|
4720
|
+
* - After an overflow of the stack, a walk with its own stack follows the same reads. It gives each node of a cycle
|
|
4721
|
+
* `#CYCLE!` at each length (SCHED.DEEP-CYCLE, D139). A demand without an overflow does no such work.
|
|
4336
4722
|
* - A node on the run side is a sink. Only `run` evaluates it, and only the host uses `run`.
|
|
4723
|
+
* - The option `selfOf` gives a node its own `self` (D135). The plan, the facts and the edges stay for each document
|
|
4724
|
+
* object, thus nodes with one document share them. The value, the reads and the place on a cycle stay for each node.
|
|
4337
4725
|
*
|
|
4338
4726
|
* The host keeps the promises of `durable`. The documents and the values of a context do not change in place.
|
|
4339
4727
|
*
|
|
4340
4728
|
* @param machine - The machine of the first structure epoch.
|
|
4341
|
-
* @param options - The options of `durable`,
|
|
4729
|
+
* @param options - The options of `durable`, the context of the host and the `self` of each node.
|
|
4342
4730
|
* @returns The schedule.
|
|
4343
4731
|
*/
|
|
4344
4732
|
export declare function schedule(machine: Machine, options?: ScheduleOptions): Schedule;
|
|
@@ -4461,12 +4849,14 @@ interface ScheduleEngine {
|
|
|
4461
4849
|
*/
|
|
4462
4850
|
read(id: string): Result;
|
|
4463
4851
|
}
|
|
4464
|
-
/** What a new engine gets beside its machine
|
|
4852
|
+
/** What a new engine gets beside its machine. These are the context of the host, the type of a bare root value and the `self` of each node. */
|
|
4465
4853
|
interface ScheduleEngineStart {
|
|
4466
4854
|
/** The first context of the host, without the root `world`. */
|
|
4467
4855
|
readonly context: Context;
|
|
4468
4856
|
/** The type of a bare root value, when the options of the harness name one. */
|
|
4469
4857
|
readonly declaredType?: string;
|
|
4858
|
+
/** The `self` of each node, when the options of the harness have `selves`. It has the form of the option of `schedule`. */
|
|
4859
|
+
readonly selfOf?: (id: string, host: Context) => unknown;
|
|
4470
4860
|
}
|
|
4471
4861
|
/**
|
|
4472
4862
|
* This function makes a new engine with no nodes. The harness makes one engine for each run. The function `schedule`
|
|
@@ -4511,6 +4901,12 @@ interface AgreeScheduleOptions {
|
|
|
4511
4901
|
readonly values?: readonly unknown[];
|
|
4512
4902
|
/** The contexts of the host at the start of the runs, one after the other. */
|
|
4513
4903
|
readonly contexts?: readonly Context[];
|
|
4904
|
+
/**
|
|
4905
|
+
* The values of the `self` of a node (SCHED.NODE-AGREES). With them, the option `selfOf` of each engine gives each
|
|
4906
|
+
* node its own `self`. Some nodes then share one document, and a change of data can give a node a new `self`. The
|
|
4907
|
+
* value `undefined` keeps the `self` of the host. The default gives each node the context of the host.
|
|
4908
|
+
*/
|
|
4909
|
+
readonly selves?: readonly unknown[];
|
|
4514
4910
|
/** The number of runs. The default is 100. */
|
|
4515
4911
|
readonly count?: number;
|
|
4516
4912
|
/** The number of commands in one run. The default is 30. */
|
|
@@ -4555,6 +4951,10 @@ interface ScheduleAgreementCounts {
|
|
|
4555
4951
|
readonly same: number;
|
|
4556
4952
|
/** The new machines. */
|
|
4557
4953
|
readonly machines: number;
|
|
4954
|
+
/** The changes of data with a new `self` of a node, only with the option `selves`. */
|
|
4955
|
+
readonly selves: number;
|
|
4956
|
+
/** The documents that a node shares with another node, only with the option `selves`. */
|
|
4957
|
+
readonly shared: number;
|
|
4558
4958
|
}
|
|
4559
4959
|
/** The outcome of `agreeSchedule`: what the harness reached, or the first disagreement. */
|
|
4560
4960
|
type ScheduleAgreement = {
|
|
@@ -4586,7 +4986,8 @@ type ScheduleAgreement = {
|
|
|
4586
4986
|
/**
|
|
4587
4987
|
* This function examines an engine of a host against an evaluation from scratch (SCHED.AGREES, R4 P4, D58). Each run
|
|
4588
4988
|
* makes a new engine and a random graph of named nodes from the document generator. Then it gives random commands:
|
|
4589
|
-
* edits, new nodes, removed nodes, the same document again, new machines and changes of data.
|
|
4989
|
+
* edits, new nodes, removed nodes, the same document again, new machines and changes of data. The option `selves`
|
|
4990
|
+
* adds a `self` for each node and documents that nodes share (SCHED.NODE-AGREES).
|
|
4590
4991
|
*
|
|
4591
4992
|
* - Each read command evaluates the whole graph from scratch two times, with the meaning of D31.
|
|
4592
4993
|
* - It then demands each node in a random order, or one node, and compares each answer with `sameResult`.
|
|
@@ -4601,105 +5002,6 @@ type ScheduleAgreement = {
|
|
|
4601
5002
|
* @returns What the harness reached, or the first read whose answer differs from the answer from scratch.
|
|
4602
5003
|
*/
|
|
4603
5004
|
export declare function agreeSchedule(engine: ScheduleEngineFactory, options?: AgreeScheduleOptions): ScheduleAgreement;
|
|
4604
|
-
/** One edge of a graph of nodes: a read of a node by another node. `NodeEdge` of a schedule is such an edge. */
|
|
4605
|
-
interface GraphEdge<Id> {
|
|
4606
|
-
/** The node that the read reaches. It is `undefined` when the read can reach each node (GRAPH.UNKNOWN). */
|
|
4607
|
-
readonly to: Id | undefined;
|
|
4608
|
-
/** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
|
|
4609
|
-
readonly lazy: boolean;
|
|
4610
|
-
}
|
|
4611
|
-
/** One node of a graph, with its edges. `NodeInfo` of a schedule is such a node. */
|
|
4612
|
-
interface GraphNode<Id> {
|
|
4613
|
-
/** The edges to the nodes that the node reads. */
|
|
4614
|
-
readonly edges: readonly GraphEdge<Id>[];
|
|
4615
|
-
/** The side of the node. A node on the run side is a sink: no edge reaches it (SCHED.SIDE). The default is `derive`. */
|
|
4616
|
-
readonly side?: Side;
|
|
4617
|
-
}
|
|
4618
|
-
/**
|
|
4619
|
-
* A graph of nodes, by name. The order of the map is the order of the nodes in each answer. The function `graph` of
|
|
4620
|
-
* 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
|
|
4621
|
-
* analysis.
|
|
4622
|
-
*/
|
|
4623
|
-
type NodeGraph<Id> = ReadonlyMap<Id, GraphNode<Id>>;
|
|
4624
|
-
/** The options of an analysis. */
|
|
4625
|
-
interface GraphOptions {
|
|
4626
|
-
/**
|
|
4627
|
-
* `true`: the analysis keeps only the eager edges with a target node. Such a read occurs in each evaluation in
|
|
4628
|
-
* which each document around it gives a value (FACTS.LAZY). The default keeps each edge.
|
|
4629
|
-
*/
|
|
4630
|
-
readonly eager?: boolean;
|
|
4631
|
-
}
|
|
4632
|
-
/** One static cycle of a graph (GRAPH.CYCLE). */
|
|
4633
|
-
interface GraphCycle<Id> {
|
|
4634
|
-
/** The nodes of the cycle, in the order of the graph. */
|
|
4635
|
-
readonly nodes: readonly Id[];
|
|
4636
|
-
/**
|
|
4637
|
-
* `true` when the eager edges with a target close the cycle. `false` when the cycle needs a lazy edge or an edge
|
|
4638
|
-
* without a target. The value of each node still comes from the demand (D31).
|
|
4639
|
-
*/
|
|
4640
|
-
readonly certain: boolean;
|
|
4641
|
-
}
|
|
4642
|
-
/**
|
|
4643
|
-
* This function gives the strongly connected components of a graph of nodes (GRAPH.SCC), with the algorithm of
|
|
4644
|
-
* Tarjan. It keeps its own stack, thus a chain of 100000 nodes does not overflow the stack of the host.
|
|
4645
|
-
*
|
|
4646
|
-
* - Each component comes after each component that it reads: the deepest component comes first.
|
|
4647
|
-
* - A node that is on no cycle is a component of one node.
|
|
4648
|
-
* - The nodes of a component are in the order of the graph.
|
|
4649
|
-
*
|
|
4650
|
-
* @param graph - The nodes, each with its edges.
|
|
4651
|
-
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4652
|
-
* @returns The components, deepest first.
|
|
4653
|
-
*/
|
|
4654
|
-
export declare function components<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
|
|
4655
|
-
/**
|
|
4656
|
-
* This function gives the height of each node: the order of a push schedule (GRAPH.ORDER). A schedule that evaluates
|
|
4657
|
-
* the nodes from the lowest height up evaluates each node after each node that it reads, except on a cycle.
|
|
4658
|
-
*
|
|
4659
|
-
* - A node that reads no node outside its component has the height 0.
|
|
4660
|
-
* - Each other node is one higher than the highest node that it reads outside its component.
|
|
4661
|
-
* - The nodes of one component have one height.
|
|
4662
|
-
* - An edge without a target reads each node that is not a sink (GRAPH.UNKNOWN).
|
|
4663
|
-
*
|
|
4664
|
-
* @param graph - The nodes, each with its edges.
|
|
4665
|
-
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4666
|
-
* @returns The height of each node, in the order of the graph.
|
|
4667
|
-
*/
|
|
4668
|
-
export declare function heights<Id>(graph: NodeGraph<Id>, options?: GraphOptions): ReadonlyMap<Id, number>;
|
|
4669
|
-
/**
|
|
4670
|
-
* This function puts the nodes in layers by their heights, in linear time (GRAPH.LAYERS). The first layer has the
|
|
4671
|
-
* height 0. Two nodes of one layer read each other only inside one component. Thus a push schedule can evaluate the
|
|
4672
|
-
* components of one layer at the same time.
|
|
4673
|
-
*
|
|
4674
|
-
* @param graph - The nodes, each with its edges.
|
|
4675
|
-
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4676
|
-
* @returns The layers, from the height 0 up. Each layer keeps the order of the graph.
|
|
4677
|
-
*/
|
|
4678
|
-
export declare function nodeLayers<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
|
|
4679
|
-
/**
|
|
4680
|
-
* This function gives the nodes that a set of observed nodes needs (GRAPH.NECESSARY). These are the observed nodes,
|
|
4681
|
-
* and each node with a path of edges from them. A push schedule evaluates only these nodes. An observed name that is
|
|
4682
|
-
* not a node of the graph adds nothing.
|
|
4683
|
-
*
|
|
4684
|
-
* @param graph - The nodes, each with its edges.
|
|
4685
|
-
* @param observed - The nodes that the host shows or reads.
|
|
4686
|
-
* @param options - The option `eager` keeps only the eager edges with a target node.
|
|
4687
|
-
* @returns The necessary nodes, in the order of the graph.
|
|
4688
|
-
*/
|
|
4689
|
-
export declare function necessary<Id>(graph: NodeGraph<Id>, observed: Iterable<Id>, options?: GraphOptions): ReadonlySet<Id>;
|
|
4690
|
-
/**
|
|
4691
|
-
* This function gives the static cycles of a graph (GRAPH.CYCLE): each component with two or more nodes, and each
|
|
4692
|
-
* node with an edge to itself. A cycle of the eager edges with a target is certain, and `check` or a host can report
|
|
4693
|
-
* it before a run. Another cycle is possible: an evaluation can skip a lazy read.
|
|
4694
|
-
*
|
|
4695
|
-
* - A component of all the edges that is also a component of the eager edges is one certain cycle.
|
|
4696
|
-
* - Each other component of all the edges is one possible cycle, and each certain cycle in it comes after it.
|
|
4697
|
-
* - A read can still fail before it occurs. Thus the demand of D31, not a static cycle, gives the value of each node.
|
|
4698
|
-
*
|
|
4699
|
-
* @param graph - The nodes, each with its edges.
|
|
4700
|
-
* @returns The cycles, deepest first.
|
|
4701
|
-
*/
|
|
4702
|
-
export declare function cycles<Id>(graph: NodeGraph<Id>): readonly GraphCycle<Id>[];
|
|
4703
5005
|
/** One vertex of the graph of attribute instances: one attribute of one node of the decorated tree (D107). */
|
|
4704
5006
|
interface AttributeVertex {
|
|
4705
5007
|
/** The name of the vertex: the JSON text of the place of the node with the name of the attribute after it. */
|
|
@@ -4711,6 +5013,8 @@ interface AttributeVertex {
|
|
|
4711
5013
|
readonly type: string;
|
|
4712
5014
|
/** `true` when the kind of the node declares the attribute `circular` (TREE.CIRCULAR-CHECK). Else the field is absent. */
|
|
4713
5015
|
readonly circular?: true;
|
|
5016
|
+
/** The arguments of an instance of an attribute with parameters (TREE.AT-CHECK). Else the field is absent. */
|
|
5017
|
+
readonly args?: Readonly<Record<string, Json>>;
|
|
4714
5018
|
}
|
|
4715
5019
|
/** One read of an attribute by the code of another attribute (D107). */
|
|
4716
5020
|
interface AttributeEdge {
|
|
@@ -5072,5 +5376,5 @@ interface SampleOptions {
|
|
|
5072
5376
|
* @returns The type.
|
|
5073
5377
|
*/
|
|
5074
5378
|
export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
|
|
5075
|
-
export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AttributeAnswer, AttributeCell, AttributeCycle, AttributeDeclaration, AttributeEdge, AttributeGraph, AttributeGraphOptions, AttributeRung, AttributeTrace, AttributeVertex, Cap, CapsRule, CheckOptions, CircularDeclaration, CircularRule, Classification, Closure, Code, CollectDeclaration, CollectRule, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Declared, 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, PlanRunOptions, PrepareOptions, PrintOptions, Random, Read, ReadPrints, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayCausePartsJson, ReplayEntry, ReplayEntryJson, ReplayErrorJson, ReplayExceptionJson, ReplayLog, ReplayLogJson, ReplayOptions, ReplayPartJson, ReplayPartsJson, ReplayResultJson, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleAgreement, ScheduleAgreementCounts, ScheduleCounts, ScheduleEngine, ScheduleEngineFactory, ScheduleEngineStart, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepKey, StepLadder, StepNeed, StepReason, StepRefusal, StepSpec, StepWalk, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxEnvelopes, SyntaxFixity, SyntaxForm, SyntaxFormArgs, SyntaxHeader, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TreeOptions, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, WalkTypeInput, Walker, World, WorldEntry, WorldIssue, WorldOptions, WorldPart };
|
|
5379
|
+
export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AtArgs, AtEquation, AtRule, AttributeAnswer, AttributeCell, AttributeCycle, AttributeDeclaration, AttributeEdge, AttributeGraph, AttributeGraphOptions, AttributeRung, AttributeTrace, AttributeVertex, Cap, CapsRule, CheckOptions, CircularDeclaration, CircularRule, Classification, Closure, Code, CodecFinding, CodecLaw, CodecLawsOptions, CodecProbe, CollectDeclaration, CollectRule, CompileInput, CompiledEvaluator, CompiledPart, CompiledPath, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, CycleIssue, Declared, 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, PlanRunOptions, PrepareOptions, PrintOptions, Random, Read, ReadPrints, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayCausePartsJson, ReplayEntry, ReplayEntryJson, ReplayErrorJson, ReplayExceptionJson, ReplayLog, ReplayLogJson, ReplayOptions, ReplayPartJson, ReplayPartsJson, ReplayResultJson, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleAgreement, ScheduleAgreementCounts, ScheduleCounts, ScheduleEngine, ScheduleEngineFactory, ScheduleEngineStart, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepKey, StepLadder, StepNeed, StepReason, StepRefusal, StepSpec, StepWalk, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxConstructs, SyntaxEnvelopes, SyntaxFixity, SyntaxForm, SyntaxFormArgs, SyntaxHeader, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TreeOptions, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, WalkTypeInput, Walker, World, WorldEntry, WorldIssue, WorldOptions, WorldPart };
|
|
5076
5380
|
//# sourceMappingURL=index.d.ts.map
|