@mark1russell7/coeval 0.9.0 → 0.11.0

package/build/index.js

@@ -368,6 +368,21 @@ function equationType(kind) {
 	return parts?.of ?? parts?.rest?.of;
 }
 /**
+* This function gives the effects that the contract of a kind declares for a verb (VERB.EFFECTS, D49). For `eval`,
+* the field `effects` declares them, and a kind without the field declares no effect. For another verb, the entry of
+* `verbEffects` declares them. `check` and `conforms` read the declarations with this one function.
+*
+* @param kind - The kind.
+* @param verb - The verb.
+* @returns The declaration in the form of `effects`, or `undefined` when the contract does not declare the effects of
+*   the verb.
+*/
+function effectsOfVerb(kind, verb) {
+	if (verb === "eval") return kind.effects ?? [];
+	const table = kind.verbEffects;
+	return table !== void 0 && Object.hasOwn(table, verb) ? table[verb] : void 0;
+}
+/**
 * This function tells if an entry of the world is a kind.
 *
 * @param entry - The entry.
@@ -546,6 +561,10 @@ const STD_DOMAINS = {
 		is: (value) => value === null,
 		summary: "The value null."
 	},
+	undefined: {
+		is: (value) => value === void 0,
+		summary: "The value undefined. A document holds it as the extension ext.undefined."
+	},
 	bool: {
 		is: (value) => typeof value === "boolean",
 		summary: "A truth value: true or false."
@@ -3574,7 +3593,7 @@ function compileNode(c, value, place, declared, depth, address = false) {
 	} catch (error) {
 		return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
 	}
-	const done = finish$1(c, meta, placedCode(inner, place, name), void 0);
+	const done = finish$1(c, meta, TOTAL.has(inner) ? inner : placedCode(inner, place, name), void 0);
 	if (frees === void 0 || kind === void 0 || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
 	const free = freeOf(doc, kind, split.parts, frees);
 	if (free === void 0) return done;
@@ -3808,6 +3827,22 @@ function copyPlain(value, memo) {
 	return out;
 }
 /**
+* The compiled code that cannot fail (PLAN.TOTAL). Such code gives a value and throws nothing. It does not read its
+* context or its runtime. Only the kits of the kernel mark code, thus the code of a host always gets its grant.
+*/
+const TOTAL = /* @__PURE__ */ new WeakSet();
+/**
+* This function marks compiled code that cannot fail (PLAN.TOTAL). Then `compileNode` does not wrap the code in
+* `placedCode`, thus a literal costs one call. The kits of the kernel use it. The package does not export it.
+*
+* @param code - The code. It gives a value and throws nothing. It does not read its context or its runtime.
+* @returns The same code.
+*/
+function totalCode(code) {
+	TOTAL.add(code);
+	return code;
+}
+/**
 * This function gives the code of a document: the code of its evaluator, with the place of each error and of each
 * exception. The code gets the context that its grant permits, thus a compiled parent cannot widen it (CAP.NARROW-CODE).
 */
@@ -5760,16 +5795,27 @@ const EACH$2 = /* @__PURE__ */ Object.freeze([[]]);
 /** No declared effect. One list serves each visit without effects. */
 const NO_EFFECTS = /* @__PURE__ */ Object.freeze([]);
 /**
-* This function gives the effects that the contract of the kind of a visit declares, as keys (FACTS.EFFECTS). The
-* text `"type"` gives the type of the document after each alias. A visit without a kind declares no effect. `check`,
-* `factsOf` and `effectsOf` read the declarations with this one function (D27).
+* This function gives the effects that the contract of the kind of a visit declares for a verb, as keys
+* (FACTS.EFFECTS, VERB.EFFECTS). The text `"type"` gives the type of the document after each alias. A visit without a
+* kind declares no effect. `check`, `factsOf` and `effectsOf` read the declarations with this one function (D27).
 *
 * @param v - The visit.
+* @param verb - The verb. The default is `eval`. A kind without a declaration for the verb gives no effect.
 * @returns The keys of each declared effect, in the order of the contract.
 */
-function declaredEffects(v) {
-	const effects = v.kind?.effects;
-	if (effects === void 0 || effects.length === 0) return NO_EFFECTS;
+function declaredEffects(v, verb = "eval") {
+	return verbDeclared(v, verb) ?? NO_EFFECTS;
+}
+/**
+* This function gives the effects that the contract of the kind of a visit declares for a verb, as keys. The result
+* is `undefined` when the contract has no declaration for the verb (D49). A visit without a kind declares no effect
+* for `eval` and no declaration for another verb.
+*/
+function verbDeclared(v, verb) {
+	if (v.kind === void 0) return verb === "eval" ? NO_EFFECTS : void 0;
+	const effects = effectsOfVerb(v.kind, verb);
+	if (effects === void 0) return void 0;
+	if (effects.length === 0) return NO_EFFECTS;
 	return effects === "type" ? [v.typePath ?? []] : effects.map((kind) => kind.split("."));
 }
 /**
@@ -5820,7 +5866,9 @@ function capReason(v, kind, allowed) {
 *   A run does not always fail there, thus a type issue is a static finding, not an error of a run.
 *
 * The check asks the ladder for the verb of the options, `eval` by default (VERB.CHECK). The shapes, the paths and the
-* names follow the contracts, thus they are the same for each verb. Only `eval` checks the declared effects.
+* names follow the contracts, thus they are the same for each verb. The check tests the effects that each contract
+* declares for the verb: `effects` for `eval`, and the entry of `verbEffects` for another verb (VERB.EFFECTS). A kind
+* without a declaration for the verb gives no `#CAP!` and no `#CALC!` for an effect.
 *
 * @param machine - The world and the code of the evaluators.
 * @param doc - The document, as JSON.
@@ -6001,7 +6049,6 @@ function checkAll(machine, doc, options, nodes, seen = /* @__PURE__ */ new Set()
 		issues.push(issue);
 		if (current !== void 0) current.marked = true;
 	};
-	const effects = verb === "eval";
 	const allowed = options.caps === void 0 ? void 0 : permitsOf(machine);
 	const waits = options.run === true ? /* @__PURE__ */ new Map() : void 0;
 	const drives = [];
@@ -6072,7 +6119,8 @@ function checkAll(machine, doc, options, nodes, seen = /* @__PURE__ */ new Set()
 			});
 		}
 		const caps = v.caps;
-		const declared = effects ? declaredEffects(v) : NO_EFFECTS;
+		const stated = verbDeclared(v, verb);
+		const declared = stated ?? NO_EFFECTS;
 		if (allowed !== void 0 && caps !== void 0) {
 			for (const kind of declared) if (!allowed(caps, kind)) push({
 				code: "#CAP!",
@@ -6094,14 +6142,14 @@ function checkAll(machine, doc, options, nodes, seen = /* @__PURE__ */ new Set()
 					},
 					index: issues.length,
 					node: current,
-					wait: !effects
+					wait: false
 				};
 				drives.push(chain);
 			} else if (runner) chain = up ?? true;
 			waits.set(v, chain);
 			if (typeof chain === "object" && !chain.wait) {
 				const rule = allowed ?? permits;
-				chain.wait = declared.some((kind) => caps === void 0 || rule(caps, kind));
+				chain.wait = stated === void 0 || declared.some((kind) => caps === void 0 || rule(caps, kind));
 			}
 			const first = declared[0];
 			if (!runner && first !== void 0) push({
@@ -6853,9 +6901,13 @@ function formulaKinds() {
 		}
 	};
 }
-/** This function gives the type of a value of a profile: the value itself as `one`. `undefined` and a function give `unknown`. */
+/**
+* This function gives the type of a value of a profile: the value itself as `one`. `undefined` gives the base type
+* `undefined`, because JSON and thus `one` cannot hold it (D48). A function gives `unknown`.
+*/
 function valueType(value) {
-	return value === void 0 || typeof value === "function" ? "unknown" : { one: [value] };
+	if (value === void 0) return "undefined";
+	return typeof value === "function" ? "unknown" : { one: [value] };
 }
 /** This function tells if a value has the form of a signature: a record with `params` as a list, and `to`. */
 function isSignature(value) {
@@ -6875,14 +6927,14 @@ function listText(names) {
 	return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
 }
 /**
-* This function tells if a signature takes a count of arguments. A parameter of the type `unknown` at the end is
-* optional, because a missing argument is `undefined`.
+* This function tells if a signature takes a count of arguments. A parameter at the end is optional when its type
+* holds `undefined`, because a missing argument is `undefined`. `unknown` and the base type `undefined` hold it.
 *
 * @returns `undefined` when the number is correct, or else the text of the numbers that the signature takes.
 */
 function arityOf(sig, count, domains) {
 	let least = sig.params.length;
-	while (least > 0 && isUnknown(sig.params[least - 1], domains)) least -= 1;
+	while (least > 0 && member(void 0, sig.params[least - 1], domains)) least -= 1;
 	const most = sig.rest === void 0 ? sig.params.length : Number.POSITIVE_INFINITY;
 	if (count >= least && count <= most) return void 0;
 	if (most === Number.POSITIVE_INFINITY) return `at least ${argumentsText(least)}`;
@@ -7140,6 +7192,7 @@ function formulaTypes(profile) {
 		"formula.ext": { synth: (input) => {
 			const name = nameOf(input);
 			if (profile.ext !== void 0 && Object.hasOwn(profile.ext, name)) return "unknown";
+			if (name === "undefined") return "undefined";
 			if (name === "number") return "number";
 			return name === "domain" ? domainTypeOf(input.doc.value, input.machine.domains) : "unknown";
 		} }
@@ -7186,6 +7239,7 @@ const PROFILE_KEYS = /* @__PURE__ */ Object.freeze([
 	"check",
 	"combine",
 	"pure",
+	"pureExt",
 	"volatile",
 	"sigs"
 ]);
@@ -7326,7 +7380,7 @@ function formulaCode(profile) {
 	return {
 		"formula.lit": compiled(({ doc }) => {
 			const result = ok(doc.value);
-			return () => result;
+			return totalCode(() => result);
 		}),
 		"formula.ref": compiled(({ doc, parts, fill, address, machine }) => {
 			const path = doc.value;
@@ -7341,7 +7395,7 @@ function formulaCode(profile) {
 		"formula.step": compiled(({ doc, parts, fill }) => {
 			if (parts.length === 0) {
 				const same = ok(doc);
-				return () => same;
+				return totalCode(() => same);
 			}
 			return (ctx, rt) => {
 				const values = valuesOf(parts, ctx, rt);
@@ -7600,9 +7654,12 @@ function makeKnown(profile) {
 		return hasExt(name) ? true : `The language has no extension ${name}.`;
 	};
 }
-/** The facts of an extension of the profile. It gets the context, thus it can read outside `resolve`. */
+/**
+* The facts of an extension of the profile that `pureExt` does not name. It gets the context, thus it can read outside
+* `resolve`.
+*/
 const NOT_PURE = /* @__PURE__ */ Object.freeze({ pure: false });
-/** The facts of a standard extension. */
+/** The facts of a standard extension, and of an extension that `pureExt` names. */
 const PURE = /* @__PURE__ */ Object.freeze({ pure: true });
 /** The lazy rule of a lazy operation: it covers each argument. */
 const EACH_PART = /* @__PURE__ */ Object.freeze([/* @__PURE__ */ Object.freeze({})]);
@@ -7612,7 +7669,8 @@ const EACH_PART = /* @__PURE__ */ Object.freeze([/* @__PURE__ */ Object.freeze({
 *
 * - An operation of `lazy` has a lazy rule for each argument.
 * - An operation is pure when the profile names it in `pure`, or when `pure` is `true`. A volatile operation is not pure.
-* - A standard extension is pure. An extension of the profile gets the context, thus it is not pure.
+* - A standard extension is pure. An extension of the profile is pure only when the profile names it in `pureExt` (D47).
+*   Such an extension keeps C4: it reads the context only through `resolve`.
 *
 * Equal profiles give the same hook (D46).
 *
@@ -7626,10 +7684,14 @@ function formulaFacts(profile = {}) {
 function makeFacts(profile, known) {
 	const volatile = new Set(profile.volatile ?? []);
 	const pure = profile.pure === true ? void 0 : new Set(profile.pure ?? []);
+	const pureExt = new Set(profile.pureExt ?? []);
 	return (path, code) => {
 		if (code !== "formula.op" && code !== "formula.ext") return void 0;
 		const name = path.slice(1).join(".");
-		if (code === "formula.ext") return profile.ext !== void 0 && Object.hasOwn(profile.ext, name) ? NOT_PURE : Object.hasOwn(STD_EXT, name) ? PURE : void 0;
+		if (code === "formula.ext") {
+			if (profile.ext !== void 0 && Object.hasOwn(profile.ext, name)) return pureExt.has(name) ? PURE : NOT_PURE;
+			return Object.hasOwn(STD_EXT, name) ? PURE : void 0;
+		}
 		if (known(path, code) !== true) return void 0;
 		const isVolatile = volatile.has(name);
 		const lazy = profile.lazy !== void 0 && Object.hasOwn(profile.lazy, name);
@@ -9572,9 +9634,10 @@ function generate(world, options) {
 	const keys = options.keys ?? KEYS;
 	const steps = options.steps ?? 2;
 	const roots = options.roots ?? ROOTS;
+	const defaultStep = Object.hasOwn(world.defaults, "step");
 	const stepTypes = types.filter((type) => {
 		const found = lookupKind(world, type);
-		return found.ok && Object.hasOwn(found.kind.verbs, "step");
+		return found.ok && (defaultStep || Object.hasOwn(found.kind.verbs, "step"));
 	});
 	const unknownNames = Object.keys(world.kinds).filter((key) => {
 		const entry = world.kinds[key];
@@ -9641,7 +9704,10 @@ function generate(world, options) {
 		if (options.own !== void 0 && options.own.length > 0 && rng.chance(.03)) out["own"] = { eval: rng.pick(options.own) };
 		return out;
 	};
-	/** A path from a root (D10). It uses the names in scope, and sometimes a step document. */
+	/**
+	* A path from a root (D10). It uses the names in scope, and sometimes a step document. The kind of a step document
+	* has the verb `step`, or the default of the world for `step` serves it.
+	*/
 	const pathFor = (pos, refKind) => {
 		if (rng.chance(malformed)) return rng.pick([
 			"names",
@@ -10252,13 +10318,15 @@ function typesNaming(world, name, verb) {
 /** This function gives the facts of the kind of a type. The hook `facts` of the machine wins over the contract. */
 function contractOf(env, kind, typePath, caps) {
 	const facts = env.machine.facts?.(typePath, env.name);
-	const effects = kind.effects;
+	const own = effectsOfVerb(kind, env.verb);
+	const effects = own ?? kind.effects;
 	const declared = effects === void 0 ? [] : effects === "type" ? [typePath] : effects;
 	return {
 		declared,
 		pure: (facts?.pure ?? kind.pure) === true,
 		lazy: facts?.lazy ?? kind.lazy,
 		describes: env.verb === "eval",
+		declares: own !== void 0,
 		caps: caps ?? [...declared, "probe"]
 	};
 }
@@ -10654,8 +10722,10 @@ function checkShot(env, sample, contract, scenario, shot) {
 	const keyOf = (part) => shot.keys[part] ?? String(part);
 	for (const call of shot.calls) if (!call.context.caps.every((cap) => permits(docCaps, cap))) report(env, "C1", `The code gives the part ${keyOf(call.part)} ${capsText(call.context.caps)}, and its document has ${capsText(docCaps)}.`, probe);
 	for (const effect of shot.caused) if (!effect.context.caps.every((cap) => permits(docCaps, cap))) report(env, "C1", `The code gives its effect ${effect.kind} ${capsText(effect.context.caps)}, and its document has ${capsText(docCaps)}.`, probe);
+	if (contract.declares) {
+		for (const effect of shot.caused) if (!permits(contract.declared, effect.kind)) report(env, "C2", `The code causes the effect ${effect.kind}, and the contract of ${sample.type} declares ${contract.declared.length === 0 ? "no effects" : capsText(contract.declared)}${env.verb === "eval" ? "" : ` for the verb ${env.verb}`}.`, probe);
+	}
 	if (contract.describes) {
-		for (const effect of shot.caused) if (!permits(contract.declared, effect.kind)) report(env, "C2", `The code causes the effect ${effect.kind}, and the contract of ${sample.type} declares ${contract.declared.length === 0 ? "no effects" : capsText(contract.declared)}.`, probe);
 		const first = shot.caused[0];
 		if (contract.pure && first !== void 0) report(env, "C4", `The kind ${sample.type} is pure, and the code causes the effect ${first.kind}.`, probe);
 		if (shot.result.ok) sample.split.parts.forEach((_slot, index) => {
@@ -12032,6 +12102,7 @@ function samplesAt(values, closed, depth) {
 	const records = [];
 	let lists = false;
 	for (const value of values) if (value === null) bases.add("null");
+	else if (value === void 0) bases.add("undefined");
 	else if (typeof value === "boolean") bases.add("bool");
 	else if (typeof value === "number") bases.add("number");
 	else if (typeof value === "string") bases.add("text");
@@ -12042,6 +12113,7 @@ function samplesAt(values, closed, depth) {
 	else return "unknown";
 	for (const base of [
 		"null",
+		"undefined",
 		"bool",
 		"number",
 		"text"
@@ -12069,7 +12141,7 @@ function samplesAt(values, closed, depth) {
 * This function infers a value type from sample values (TYPE.SAMPLES), as a type provider of F# does. A host uses it
 * for the type of a root, for example from some events.
 *
-* - `null`, a truth value, a number and a text give their base types, not their values.
+* - `null`, `undefined`, a truth value, a number and a text give their base types, not their values.
 * - The items of each list join into one type of items.
 * - All records join into one record with each key of the samples. A key that a record does not have is optional.
 * - Values of different forms give a union, as `join` gives. No samples give `never`.
@@ -12086,6 +12158,6 @@ function typeFromSamples(values, options = {}) {
 	return samplesAt(values, options.closed === true, 0);
 }
 //#endregion
-export { ATTRIBUTE_RUNGS, CAPS_TYPE, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, agree, ask, attributeTrace, capKeys, check, checkLatent, checkSteps, checkWorld, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, print, random, recorder, ref, reference, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
+export { ATTRIBUTE_RUNGS, CAPS_TYPE, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, agree, ask, attributeTrace, capKeys, check, checkLatent, checkSteps, checkWorld, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, effectsOfVerb, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, print, random, recorder, ref, reference, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
 
 //# sourceMappingURL=index.js.map