@intentius/chant 0.124.13 → 0.124.15

package/dist/lint/rules/single-concern-file.js

@@ -0,0 +1,71 @@
+import * as ts from "typescript";
+/**
+ * COR013: Single-concern file
+ *
+ * Advisory rule that flags files mixing resource Declarables (e.g. Bucket,
+ * Function, Role) with property/config Declarables (e.g. BucketEncryption,
+ * VersioningConfiguration) as `new` expressions.
+ *
+ * Heuristic: class names containing "Configuration", "Encryption", "Policy",
+ * "Rule", "Setting", "Block", "Specification" are considered property-kind.
+ * All other capitalized `new` expressions are considered resource-kind.
+ *
+ * Triggers when a single file has `new` expressions for both kinds.
+ */
+const PROPERTY_KIND_PATTERNS = [
+    "Configuration",
+    "Encryption",
+    "Policy",
+    "Rule",
+    "Setting",
+    "Block",
+    "Specification",
+];
+function isPropertyKindClass(className) {
+    return PROPERTY_KIND_PATTERNS.some(pattern => className.includes(pattern));
+}
+function isResourceKindClass(className) {
+    return /^[A-Z]/.test(className) && !isPropertyKindClass(className);
+}
+function collectNewExpressions(node, sourceFile, results) {
+    if (ts.isNewExpression(node)) {
+        const className = node.expression.getText(sourceFile);
+        // Only consider capitalized class names (likely Declarable constructors)
+        if (/^[A-Z]/.test(className) || /\.[A-Z]/.test(className)) {
+            // Extract the simple class name (after any dot for qualified access like aws.Bucket)
+            const simpleName = className.includes(".")
+                ? className.split(".").pop()
+                : className;
+            results.push({ className: simpleName, node });
+        }
+    }
+    ts.forEachChild(node, child => collectNewExpressions(child, sourceFile, results));
+}
+export const singleConcernFileRule = {
+    id: "COR013",
+    severity: "info",
+    category: "style",
+    description: "Flags files mixing resource Declarables with configuration Declarables",
+    check(context) {
+        const newExpressions = [];
+        collectNewExpressions(context.sourceFile, context.sourceFile, newExpressions);
+        const resourceExpressions = newExpressions.filter(e => isResourceKindClass(e.className));
+        const propertyExpressions = newExpressions.filter(e => isPropertyKindClass(e.className));
+        // Only flag if the file has both kinds
+        if (resourceExpressions.length === 0 || propertyExpressions.length === 0) {
+            return [];
+        }
+        // Report a single diagnostic at the file level (first line)
+        const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(0);
+        return [
+            {
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "COR013",
+                severity: "info",
+                message: "COR013: File mixes resource Declarables with configuration Declarables — consider splitting into separate files",
+            },
+        ];
+    },
+};

package/dist/lint/rules/sys001-no-literal-key.js

@@ -0,0 +1,60 @@
+import ts from "typescript";
+/**
+ * SYS001: a `decide` backend's key is never a literal (#2740, core's since
+ * #2828).
+ *
+ * A key is `{ env: "VARIABLE" }` or a brokered capability
+ * (`{ capability: "inference", member: "box" }`, #2726). A string written
+ * where a key goes is a credential in git history, and a box that holds one
+ * fails `workspace check` with WSP121 as well.
+ *
+ * Fires on a `key` property whose value is a string or template literal,
+ * inside a backend of a `backends` object that belongs to `decide`: the
+ * `decide` block of a config object (`decide: { backends: ... }`) or the
+ * options of a `decide(...)` step. A `backends` object anywhere else, such as
+ * a Terraform backend's `key`, is not a decide backend and is left alone.
+ * The id keeps the SYS prefix it had in the systemone lexicon.
+ */
+function keyText(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        return name.text;
+    return undefined;
+}
+const isLiteral = (node) => ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isTemplateExpression(node);
+const isDecideCall = (node) => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "decide";
+export const noLiteralKeyRule = {
+    id: "SYS001",
+    severity: "error",
+    category: "security",
+    description: "A decide backend key is { env } or a brokered capability, never a literal string",
+    check(context) {
+        const diagnostics = [];
+        const source = context.sourceFile;
+        const visit = (node, scope) => {
+            let within = scope;
+            if (isDecideCall(node))
+                within = "decide";
+            else if (ts.isPropertyAssignment(node)) {
+                const key = keyText(node.name);
+                if (key === "decide")
+                    within = "decide";
+                else if (key === "backends" && scope === "decide")
+                    within = "backends";
+                if (scope === "backends" && key === "key" && isLiteral(node.initializer)) {
+                    const { line, character } = source.getLineAndCharacterOfPosition(node.initializer.getStart(source));
+                    diagnostics.push({
+                        ruleId: "SYS001",
+                        severity: "error",
+                        message: 'Literal backend key: use { env: "VARIABLE" } or a brokered capability ({ capability, member }) instead',
+                        file: context.filePath,
+                        line: line + 1,
+                        column: character + 1,
+                    });
+                }
+            }
+            ts.forEachChild(node, (child) => visit(child, within));
+        };
+        visit(source, "outside");
+        return diagnostics;
+    },
+};

package/dist/lint/selectors.js

@@ -0,0 +1,168 @@
+import * as ts from "typescript";
+/**
+ * Registry of named selectors.
+ */
+const selectorRegistry = new Map();
+/**
+ * Recursively collect nodes matching a predicate.
+ */
+export function collectNodes(root, predicate) {
+    const results = [];
+    function visit(node) {
+        if (predicate(node)) {
+            results.push(node);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(root);
+    return results;
+}
+/**
+ * Built-in selector: matches `new X(...)` constructor calls (resource instantiations).
+ */
+function selectResource(sf) {
+    return collectNodes(sf, (node) => ts.isNewExpression(node));
+}
+/**
+ * Built-in selector: matches any resource — alias for `resource`.
+ */
+function selectAnyResource(sf) {
+    return selectResource(sf);
+}
+/**
+ * Built-in selector: matches string literal nodes.
+ */
+function selectStringLiteral(sf) {
+    return collectNodes(sf, (node) => ts.isStringLiteral(node));
+}
+/**
+ * Built-in selector: matches exported declaration names.
+ */
+function selectExportName(sf) {
+    return collectNodes(sf, (node) => {
+        if (ts.isVariableStatement(node)) {
+            return node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        }
+        if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
+            return node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        }
+        return false;
+    });
+}
+/**
+ * Built-in selector: matches import source strings.
+ */
+function selectImportSource(sf) {
+    return collectNodes(sf, (node) => {
+        if (ts.isImportDeclaration(node)) {
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Built-in selector: matches property assignments.
+ */
+function selectProperty(sf) {
+    return collectNodes(sf, (node) => ts.isPropertyAssignment(node));
+}
+/**
+ * Built-in selector: matches the type argument of `new X<Type>(...)` expressions.
+ */
+function selectResourceType(sf) {
+    return collectNodes(sf, (node) => {
+        if (ts.isNewExpression(node) && node.typeArguments && node.typeArguments.length > 0) {
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Built-in selector: matches exported const declarations.
+ */
+function selectExportedConst(sf) {
+    return collectNodes(sf, (node) => {
+        if (!ts.isVariableStatement(node))
+            return false;
+        const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        if (!hasExport)
+            return false;
+        return node.declarationList.flags === ts.NodeFlags.Const ||
+            (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+    });
+}
+// Register built-in selectors
+const builtins = [
+    ["resource", selectResource],
+    ["any-resource", selectAnyResource],
+    ["string-literal", selectStringLiteral],
+    ["export-name", selectExportName],
+    ["import-source", selectImportSource],
+    ["property", selectProperty],
+    ["resource-type", selectResourceType],
+    ["exported-const", selectExportedConst],
+];
+for (const [name, fn] of builtins) {
+    selectorRegistry.set(name, fn);
+}
+/**
+ * Register a custom selector.
+ */
+export function registerSelector(name, fn) {
+    selectorRegistry.set(name, fn);
+}
+/**
+ * Resolve a selector name (or compound expression) to a SelectorFn.
+ *
+ * Compound selectors use `>` to scope: `"resource > property"` means
+ * "find all `resource` nodes, then within each, find all `property` nodes".
+ */
+export function resolveSelector(name) {
+    // Check for compound selector
+    if (name.includes(">")) {
+        const parts = name.split(">").map((s) => s.trim());
+        const fns = parts.map((part) => {
+            const fn = selectorRegistry.get(part);
+            if (!fn) {
+                throw new Error(`Unknown selector: "${part}"`);
+            }
+            return fn;
+        });
+        return (sf) => {
+            // Start with results from first selector
+            let nodes = fns[0](sf);
+            // For each subsequent selector, search within current nodes
+            for (let i = 1; i < fns.length; i++) {
+                const nextNodes = [];
+                for (const parent of nodes) {
+                    const childSelector = fns[i];
+                    const allMatches = childSelector(sf);
+                    for (const match of allMatches) {
+                        if (isDescendantOf(match, parent)) {
+                            nextNodes.push(match);
+                        }
+                    }
+                }
+                nodes = nextNodes;
+            }
+            return nodes;
+        };
+    }
+    const fn = selectorRegistry.get(name);
+    if (!fn) {
+        throw new Error(`Unknown selector: "${name}"`);
+    }
+    return fn;
+}
+/**
+ * Check if a node is a descendant of another node.
+ */
+function isDescendantOf(node, ancestor) {
+    let current = node.parent;
+    while (current) {
+        if (current === ancestor)
+            return true;
+        current = current.parent;
+    }
+    return false;
+}

package/dist/lint/suppressions.js

@@ -0,0 +1,129 @@
+/**
+ * Inline HCL-comment suppression (chant #2111). This file is core's small,
+ * generic half of the mechanism. It filters already-produced
+ * `PostSynthDiagnostic`s against suppression directives an entity carries,
+ * with no knowledge of which lexicon produced that entity. The other half,
+ * reading `# chant-ignore` / `# chant-ignore-file` / `# chant-ignore-block`
+ * comments out of raw `.tf` text and attaching the result to each parsed
+ * entity, is terraform-specific and lives in
+ * `lexicons/terraform/src/hcl/suppressions.ts`.
+ *
+ * Placement. The issue that asked for this weighed two options: a wrapper
+ * over `runPostSynthChecks` private to the terraform lexicon, or a
+ * `PostSynthContext` field every lexicon could share. Neither is quite what
+ * this file does. `ctx.entities` is already the one thing every
+ * `PostSynthContext` carries regardless of lexicon, and a suppression
+ * directive is inherently a fact ABOUT one entity, namely which block it
+ * anchors to, not a fact about the run as a whole. That is the same reasoning
+ * that already lets each lexicon's `Declarable` carry its own `props` shape
+ * (`TerraformEntity.props`, `K8sEntity.props`, and so on), so the hook here
+ * is a plain, duck-typed optional field, `suppressions`, that any entity MAY
+ * carry beside its `props`, read generically through `entitySuppressions()`
+ * below. Choosing this over a `PostSynthContext.suppressions` field needed no
+ * change to `PostSynthContext`, `Declarable`, or any of the places that
+ * construct a context (`./post-synth.ts`'s `runPostSynthChecks`, `chant
+ * audit`'s `../audit/core.ts`, and the two test-utils builders). Every one
+ * of them already hands `applyInlineSuppressions` below `ctx.entities`, so a
+ * lexicon that wants this (k8s manifests are the epic's other named
+ * candidate) adopts the convention on its own entities, with zero further
+ * core changes.
+ *
+ * `rules` (a project's `lint.rules`) is optional here on purpose. `chant
+ * build` has one to pass, so `ignorable: false` works there; `chant audit`'s
+ * audit-core path does not thread a project config through at all today, see
+ * `../audit/core.ts`, so it calls this with `rules` omitted. Every rule
+ * reads as ignorable in that path, the same default this module
+ * gives an unconfigured rule id everywhere else.
+ */
+/** An expired suppression is reported once as its own finding, not dropped. */
+export const SUPPRESSION_EXPIRED_ID = "SUPP001";
+/** A `chant-ignore-file` found anywhere but the first non-blank line. */
+export const SUPPRESSION_MISPLACED_FILE_ID = "SUPP002";
+/** A directive explicitly names a rule id configured `ignorable: false`. */
+export const SUPPRESSION_UNIGNORABLE_ID = "SUPP003";
+/** Read an entity's directives, if it carries any (duck-typed; see module doc). */
+export function entitySuppressions(entity) {
+    if (!entity)
+        return [];
+    const s = entity.suppressions;
+    return Array.isArray(s) ? s : [];
+}
+/** Default is ignorable (per the issue); only an explicit `{ ignorable: false }` option denies it. */
+function isIgnorable(rules, id) {
+    const cfg = rules?.[id];
+    if (!Array.isArray(cfg))
+        return true;
+    const options = cfg[1];
+    return options?.ignorable !== false;
+}
+function namesId(ids, checkId) {
+    return ids === "all" || ids.has(checkId);
+}
+function isExpired(expires, today) {
+    if (!expires)
+        return false;
+    const parsed = new Date(`${expires}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime()))
+        return false;
+    return parsed.getTime() < today.getTime();
+}
+/**
+ * Apply inline (`# chant-ignore*`) suppression to a set of post-synth
+ * diagnostics. `entities` is `ctx.entities`, the same map every
+ * `PostSynthContext` already carries. `rules` is the project's `lint.rules`,
+ * for `ignorable: false`; see this module's doc comment for why it is
+ * optional. `today` is injectable so an expiry test doesn't depend on the
+ * clock.
+ */
+export function applyInlineSuppressions(diagnostics, entities, rules, today = new Date()) {
+    const kept = [];
+    const suppressed = [];
+    const meta = [];
+    const reported = new Set();
+    const reportMeta = (d, checkId, message) => {
+        const dedupeKey = `${checkId}:${d.key}`;
+        if (reported.has(dedupeKey))
+            return;
+        reported.add(dedupeKey);
+        meta.push({ checkId, severity: "warning", file: d.file, line: d.line, message });
+    };
+    // Expired and misplaced directives are findings on their own. They don't
+    // need a matching diagnostic to be worth reporting, so every directive
+    // attached to any entity is checked once here, deduplicated by its own
+    // identity (a directive attached to several entities, as a file-level one
+    // is, would otherwise be reported once per entity).
+    for (const entity of entities.values()) {
+        for (const d of entitySuppressions(entity)) {
+            if (d.misplaced) {
+                reportMeta(d, SUPPRESSION_MISPLACED_FILE_ID, `chant-ignore-file at ${d.file}:${d.line} is not the first non-blank line of the file, so it has no effect. Move it to the top.`);
+                continue;
+            }
+            if (isExpired(d.expires, today)) {
+                reportMeta(d, SUPPRESSION_EXPIRED_ID, `Suppression at ${d.file}:${d.line} expired ${d.expires} and no longer applies.`);
+            }
+        }
+    }
+    for (const diag of diagnostics) {
+        const entity = diag.entity ? entities.get(diag.entity) : undefined;
+        let matched;
+        for (const d of entitySuppressions(entity)) {
+            if (d.misplaced)
+                continue;
+            if (isExpired(d.expires, today))
+                continue;
+            if (!namesId(d.ids, diag.checkId))
+                continue;
+            if (d.ids !== "all" && !isIgnorable(rules, diag.checkId)) {
+                reportMeta(d, SUPPRESSION_UNIGNORABLE_ID, `${diag.checkId} is configured \`ignorable: false\`; the ${d.form} at ${d.file}:${d.line} naming it has no effect.`);
+                continue;
+            }
+            matched = d;
+            break;
+        }
+        if (matched)
+            suppressed.push(diag);
+        else
+            kept.push(diag);
+    }
+    return { diagnostics: kept, suppressed, meta };
+}

package/dist/lint/typescript.js

@@ -0,0 +1,17 @@
+/**
+ * The TypeScript compiler API chant parses with, for lexicon lint rules and
+ * language services (#3864).
+ *
+ * Core parses every source file with its own `typescript` dependency, which
+ * stays on 5.x. A lexicon that imported `typescript` itself got the project's
+ * copy instead, and a project on TypeScript 7 has no JS compiler API there:
+ * `ts.isImportDeclaration` is undefined and every rule threw. Even when two
+ * 5.x copies load, their `SyntaxKind` numbers can differ between minors, so a
+ * rule must test nodes with the same module that built them.
+ *
+ * Lexicons import `ts` from here, never from "typescript":
+ *
+ *     import { ts } from "@intentius/chant/lint/typescript";
+ */
+import * as ts from "typescript";
+export { ts };

package/dist/live-endpoint.js

@@ -0,0 +1,113 @@
+/**
+ * chant #1166 — let a declared `environment` carry its own endpoint so
+ * `--live --env <name>` is self-sufficient.
+ *
+ * The bug this closes: `chant graph --live --env floci` (and `lifecycle
+ * diff`/`plan`) observe a stack by shelling out through each lexicon's
+ * `describeResources()`. For AWS that shell-out honors the ambient
+ * `AWS_ENDPOINT_URL` env var — when a project's `floci` environment is a local
+ * emulator (`http://localhost:4566`) but the invoking shell never exported
+ * that var, the AWS CLI silently targets real AWS instead. The stack named
+ * after the environment doesn't exist there, so `describeResources` hits its
+ * `stackDoesNotExist` branch and returns an empty, unremarkable "nothing is
+ * deployed" — indistinguishable from the truthful answer. This cost real
+ * debugging time validating #1162's live overlay: the observation code was
+ * right, the manual repro just never set the var.
+ *
+ * The fix: `environments` in `chant.config.ts` can name an endpoint per
+ * environment (`config.ts`'s `EnvironmentDeclaration`), and {@link
+ * applyLiveEndpoint} injects it into the ambient env var each observing
+ * lexicon's CLI shell-out actually reads — but only for a var that isn't
+ * already set. Ambient always wins: a shell that already exports
+ * `AWS_ENDPOINT_URL` sees no change in behavior.
+ *
+ * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
+ * all, since that's the specific footgun — a lexicon whose environment
+ * binding is resolved from `chant.config` itself (not an ambient var) has
+ * nothing to inject here.
+ *
+ * Which var that is per lexicon is no longer written down twice (#1345). It is
+ * derived from the lexicon's own {@link EmulatorCapability.env}, which already
+ * has to name the var that points tooling at a booted emulator. The map this
+ * replaced listed aws and fly, and its prose asserted azure had no ambient
+ * endpoint var — while `lexicons/azure/src/describe-resources.ts` and
+ * `deep-observe.ts` both read `AZURE_ENDPOINT_URL` on every call, so a
+ * `--live --env floci` read against azure silently went to real Azure.
+ */
+import { environmentEndpoint } from "./config.js";
+import { emulatorsOf, endpointEnvVars } from "./op/emulator-lifecycle.js";
+/**
+ * The ambient endpoint vars a lexicon honors, from its emulator capability.
+ *
+ * A lexicon with no emulator contributes nothing, which is the same answer the
+ * hand-maintained map gave for k8s and gcp — they resolve their live
+ * target from `chant.config` itself, so there is nothing to inject.
+ */
+export function endpointEnvVarsFor(lexicon) {
+    return emulatorsOf(lexicon.emulator).flatMap((cap) => endpointEnvVars(cap));
+}
+/**
+ * Resolve `environment`'s declared endpoint (if any) from `config.environments`
+ * and apply it to the ambient env var of every lexicon in `lexicons` that has
+ * one ({@link LEXICON_ENDPOINT_ENV_VAR}) — but only when that var isn't
+ * already set. Ambient always wins (#1166): behavior for a shell that already
+ * exports `AWS_ENDPOINT_URL` is unchanged.
+ *
+ * Call before a `--live` describe/enrich pass; `restore()` in a `finally` so
+ * the injected value never leaks into a later invocation in the same process
+ * (tests, or a long-lived host like the MCP server).
+ */
+export function applyLiveEndpoint(environments, environment, lexicons, env = process.env) {
+    const endpoint = environmentEndpoint(environments, environment);
+    if (!endpoint)
+        return { restore: () => { } };
+    const applied = [];
+    const overridden = [];
+    const seen = new Set(); // a var shared by two lexicons is only reported once
+    for (const lexicon of lexicons) {
+        for (const varName of endpointEnvVarsFor(lexicon)) {
+            if (seen.has(varName))
+                continue;
+            seen.add(varName);
+            if (env[varName]) {
+                overridden.push(varName);
+                continue;
+            }
+            env[varName] = endpoint;
+            applied.push(varName);
+        }
+    }
+    const notices = [];
+    if (applied.length > 0) {
+        notices.push(`environment "${environment}" declares endpoint ${endpoint} — applied to ${applied.join(", ")} for this read`);
+    }
+    if (overridden.length > 0) {
+        notices.push(`ambient ${overridden.join(", ")} already set — keeping it over environment "${environment}"'s declared endpoint (${endpoint})`);
+    }
+    return {
+        notice: notices.length > 0 ? notices.join("; ") : undefined,
+        restore: () => {
+            for (const varName of applied)
+                delete env[varName];
+        },
+    };
+}
+/**
+ * #1166 acceptance: when a `--live` describe comes back with zero resources
+ * for a lexicon that had declared entities to look for, and nothing was
+ * already reported NOT-OBSERVED (#1089) either, that is either "genuinely
+ * nothing is deployed yet" or a misconfigured endpoint/credentials — the two
+ * are visually identical, so a caller must say so rather than stay quiet.
+ * Returns `undefined` when there is nothing to declare (no declared entities
+ * to have asked about, or the emptiness is already explained by #1089's
+ * `unobserved`).
+ */
+export function zeroResourcesWarning(lexicon, environment, declaredCount, observed) {
+    if (declaredCount === 0)
+        return undefined;
+    if (Object.keys(observed.resources).length > 0)
+        return undefined;
+    if (Object.keys(observed.unobserved).length > 0)
+        return undefined;
+    return `${lexicon}: 0 live resources for env "${environment}" (${declaredCount} declared) — check the endpoint/credentials`;
+}

package/dist/live-read-session.js

@@ -0,0 +1,76 @@
+/**
+ * One command, one read of the account (chant #2498).
+ *
+ * A `chant graph --live --traffic` against a live root reads the account
+ * twice: once for the graph's observation and once for the prediction, and
+ * each of those used to run `live-plan` twice for the document and its human
+ * render. Four `live-plan` runs for one answer, which on a drifted estate
+ * whose provider retries a deleted resource was five minutes against a
+ * consumer's three-minute budget.
+ *
+ * Nothing shared a read because nothing could: a plugin method takes options
+ * alone and cannot be handed the documents another method already holds. So
+ * the sharing is ambient instead. A command that wants its reads shared runs
+ * inside {@link withLiveReadSession}; a read that can be shared calls
+ * {@link memoLiveRead} with a key naming everything that would change its
+ * answer (root, directory, binary, flags, environment), and gets the pending
+ * or settled promise of an identical read made earlier in the same session.
+ *
+ * The scope is the session, never the process. A watch Op ticking on a
+ * schedule runs the same activity every tick and must see the account move,
+ * so outside a session {@link memoLiveRead} simply reads. A rejection is
+ * never memoised either: the next caller tries again, since a read that
+ * failed on credentials or a timeout says nothing about the next one.
+ *
+ * `AsyncLocalStorage` carries the session across every `await` under the
+ * wrapped call, which is how two plugin methods called one after the other
+ * by one handler share it without either knowing about the other.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const sessions = new AsyncLocalStorage();
+/**
+ * Run `fn` with a fresh read session, so every {@link memoLiveRead} under
+ * it with the same key is one read. A call already inside a session joins
+ * it rather than opening a nested one: the outer command is the unit of
+ * "once".
+ */
+export function withLiveReadSession(fn) {
+    if (sessions.getStore())
+        return fn();
+    return sessions.run(new Map(), fn);
+}
+/** Whether the caller is inside a {@link withLiveReadSession} scope. */
+export function inLiveReadSession() {
+    return sessions.getStore() !== undefined;
+}
+/**
+ * The result of `read()`, shared with every earlier and later call in the
+ * same session that names the same `key`. Outside a session, `read()` and
+ * nothing else. A read that rejects is dropped from the session so the next
+ * call with its key reads again.
+ */
+export function memoLiveRead(key, read) {
+    const memo = sessions.getStore();
+    if (!memo)
+        return read();
+    const shared = memo.get(key);
+    if (shared)
+        return shared;
+    const pending = read();
+    memo.set(key, pending);
+    pending.catch(() => {
+        if (memo.get(key) === pending)
+            memo.delete(key);
+    });
+    return pending;
+}
+/**
+ * A key from the facts that decide a read's answer. Sorted keys, so two
+ * callers that spell the same read in a different order share it.
+ */
+export function liveReadKey(activity, facts) {
+    const ordered = {};
+    for (const name of Object.keys(facts).sort())
+        ordered[name] = facts[name];
+    return `${activity}:${JSON.stringify(ordered)}`;
+}