kestrel.markets/src/canonical/plans.ts

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # canonical/plans — the one canonical plans-text derivation (kestrel-zs2f)
 *
 * The **canonical plans text** of an authored document set is the byte-stable printer projection
 * (ADR-0001): each document printed with the round-trip printer, joined by a blank line. It is what the
 * ledger hashes into `plans_sha256` and what a hosted `/validate` / `/sim` request carries as `source`, so
 * two authorings that parse-print equal collapse to the SAME run identity regardless of surface
 * whitespace. The derivation `documents.map(print).join("\n\n")` was hand-rolled at eight call sites (the
 * two CLI backends, the sim/grade commands, the session driver); this is its ONE owner (ARCH-REVIEW C1).
 * Pure — `print` is deterministic, no wall clock, no RNG.
 */

import { print, type KestrelNode } from "../lang/index.ts";

/** The canonical plans text of a document set: each node round-trip-printed and joined by a blank line
 * (ADR-0001). `Module` and each `Statement` are both {@link KestrelNode}s, so an armed module set,
 * a parsed `.kestrel` document, or a `.md`'s fenced blocks all derive through this one function. Pure. */
export function canonicalPlansText(documents: readonly KestrelNode[]): string {
  return documents.map((d) => print(d)).join("\n\n");
}