@telorun/analyzer 0.59.0 → 0.61.0

package/src/module-library.ts

@@ -0,0 +1,208 @@
+/**
+ * A module's **exported code** — the `exports.code:` block on a `Telo.Library`
+ * doc, which names the entry point a *sibling module's* controller bundle
+ * resolves this module's bare specifier to.
+ *
+ * ```yaml
+ * exports:
+ *   kinds:
+ *     - Store
+ *   code:
+ *     - specifier: "@telorun/kv-store"
+ *       format: js
+ *       path: ./nodejs/kv-store.mjs
+ *       source: ./nodejs/src/index.ts
+ * ```
+ *
+ * ## Why it sits under `exports:`
+ *
+ * A library already declares what crosses its boundary — the kinds importers may
+ * name, the resource instances they may `!ref`. This is the same statement about
+ * its *code*, and it gates the same way: a specifier nobody declares resolves to
+ * nothing. Putting it beside them keeps one block for "reachable from outside"
+ * rather than a second top-level key whose name (`library:` on a `Telo.Library`)
+ * meant a different thing from the kind one line above it.
+ *
+ * ## Why it is not a package URL
+ *
+ * `controllers:` names a PURL because it must be able to say `pkg:npm/…` or
+ * `pkg:cargo/…` — an ecosystem fetch. This entry never fetches: it names a file
+ * the module already ships, so `pkg:telo/local/` would be three constant segments
+ * before the first real datum. What is left after removing them is exactly these
+ * fields, and as data they are visually editable, where a query string is one
+ * opaque text box.
+ *
+ * The **model** is unchanged: `format` plus the optional platform axes build the
+ * same `ArtifactSelector` a controller candidate does, so layer matching, platform
+ * fallthrough and lazy materialization are inherited whole.
+ *
+ * ## Why the specifier is declared here
+ *
+ * A bundle imports the bare specifier `@telorun/sql`; the consumer's manifest
+ * declares the dependency as `Sql: ../sql`. Something has to connect the two, and
+ * it is the *library* that says so, once, rather than each of its consumers:
+ *
+ * - the specifier is a property of the library — its name in a host language's
+ *   ecosystem — not of the relationship, so N consumers cannot disagree about it
+ *   and adding a consumer restates nothing;
+ * - it sits beside the format, which keeps runtime **derived, never declared**:
+ *   the entry says `format: js`, and a Rust entry carries `specifier:
+ *   telorun-sql` with no runtime-keyed map anywhere.
+ *
+ * **One specifier, one entry point.** Subpaths are deliberately not
+ * representable: reproducing npm's `exports` map inside the artifact would pull a
+ * package manager's resolution semantics into Telo, which is what the "only
+ * workspace modules are de-inlined" rule refuses on `kysely`'s behalf.
+ *
+ * `Telo.Application` has no `exports:` block at all — an application is a root
+ * with no importer, so nothing could resolve a specifier to it.
+ *
+ * Browser-safe: string work only. Whether the named file EXISTS is a separate
+ * question, asked by the Node-side caller that has a directory.
+ */
+
+import {
+  ArtifactSelectorError,
+  PLATFORM_AXES,
+  selectorFromQualifiers,
+  type ArtifactSelector,
+} from "./artifact-selector.js";
+
+/** Every key an entry may carry: the two locators, plus the selector axes. */
+const KNOWN_KEYS = new Set<string>(["specifier", "path", "source", "format", ...PLATFORM_AXES]);
+
+export interface LibraryCandidate {
+  /** The bare specifier a sibling's controller bundle imports this library by. */
+  readonly specifier: string;
+  /** Module-root-relative path of the built entry point. */
+  readonly path: string;
+  /** Module-root-relative TypeScript source it is built from (`source:`), when
+   *  the entry names one. Present only while the module is a working copy; a
+   *  published artifact ships no `src/`. */
+  readonly localPath?: string;
+  readonly selector: ArtifactSelector;
+  /** Where the entry was written, for diagnostics. */
+  readonly origin: string;
+}
+
+/** Why an `exports.code` entry could not be read. Returned rather than thrown so
+ *  the analyzer can report every entry of a block, and so a reader on the load
+ *  path can carry on with the entries that are well-formed. */
+export interface LibraryCandidateProblem {
+  readonly origin: string;
+  readonly detail: string;
+}
+
+export interface LibraryCandidates {
+  readonly candidates: LibraryCandidate[];
+  readonly problems: LibraryCandidateProblem[];
+}
+
+/** Normalize a `path` / `source` value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+function requiredString(
+  entry: Record<string, unknown>,
+  key: string,
+): { value: string } | { detail: string } {
+  const raw = entry[key];
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return { detail: `'${key}' is required and must be a non-empty string.` };
+  }
+  return { value: raw.trim() };
+}
+
+/**
+ * Read the `exports.code:` block off an owner document's JSON projection.
+ *
+ * Everything malformed is a problem rather than a silent skip: an entry that
+ * cannot be read names no entry point, so a consumer's bundle falls back to
+ * *inlining* the library — the duplicated module scope this whole mechanism
+ * exists to remove — and it does so on someone else's machine.
+ */
+export function readLibraryCandidates(ownerJson: unknown): LibraryCandidates {
+  const declared = (ownerJson as { exports?: { code?: unknown } } | null)?.exports?.code;
+  const candidates: LibraryCandidate[] = [];
+  const problems: LibraryCandidateProblem[] = [];
+  if (declared === undefined) return { candidates, problems };
+  if (!Array.isArray(declared)) {
+    return {
+      candidates,
+      problems: [{ origin: "exports.code", detail: "expected a list of entries." }],
+    };
+  }
+
+  declared.forEach((raw, index) => {
+    const origin = `exports.code[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      problems.push({ origin, detail: "expected an object." });
+      return;
+    }
+    const entry = raw as Record<string, unknown>;
+
+    const unknown = Object.keys(entry).filter((key) => !KNOWN_KEYS.has(key));
+    if (unknown.length > 0) {
+      // Reported, never ignored: an unrecognized platform axis would leave the
+      // entry platform-neutral and offer a single-platform file to every host.
+      problems.push({
+        origin,
+        detail:
+          `unknown ${unknown.length === 1 ? "key" : "keys"} ${unknown.map((k) => `'${k}'`).join(", ")}. ` +
+          `Known: ${[...KNOWN_KEYS].join(", ")}.`,
+      });
+      return;
+    }
+
+    const specifier = requiredString(entry, "specifier");
+    if ("detail" in specifier) {
+      problems.push({ origin, detail: specifier.detail });
+      return;
+    }
+    const file = requiredString(entry, "path");
+    if ("detail" in file) {
+      problems.push({ origin: `${origin} ('${specifier.value}')`, detail: file.detail });
+      return;
+    }
+    // Explicit rather than inferred from the file extension: a `.mjs` can be
+    // wasm glue, and an inference rule is something every other runtime's reader
+    // would have to copy exactly.
+    const format = requiredString(entry, "format");
+    if ("detail" in format) {
+      problems.push({ origin: `${origin} ('${specifier.value}')`, detail: format.detail });
+      return;
+    }
+
+    let selector: ArtifactSelector;
+    try {
+      selector = selectorFromQualifiers(format.value, entry, `${origin} ('${specifier.value}')`);
+    } catch (err) {
+      problems.push({
+        origin: `${origin} ('${specifier.value}')`,
+        detail: err instanceof ArtifactSelectorError ? err.message : String(err),
+      });
+      return;
+    }
+
+    const source = entry.source;
+    if (source !== undefined && (typeof source !== "string" || source.trim() === "")) {
+      problems.push({
+        origin: `${origin} ('${specifier.value}')`,
+        detail: "'source' must be a non-empty string when present.",
+      });
+      return;
+    }
+
+    candidates.push({
+      specifier: specifier.value,
+      path: normalizeRelative(file.value),
+      ...(typeof source === "string" ? { localPath: normalizeRelative(source.trim()) } : {}),
+      selector,
+      origin: `${origin} ('${specifier.value}')`,
+    });
+  });
+
+  return { candidates, problems };
+}

package/src/module-metadata-scope.ts

@@ -0,0 +1,88 @@
+/**
+ * What `module.<field>` may read: the metadata an AUTHOR wrote, never the
+ * loader's own stamps.
+ *
+ * A manifest reaching its own `metadata` is a small binding with one sharp edge.
+ * By the time analysis or the runtime sees a module doc, its `metadata` also
+ * carries fields nothing authored — `source` and `sourceLine` (the loader's
+ * provenance), `module`, `moduleGlobals`, `exportedKinds`, `reExportedKinds`,
+ * `forwardedExport` (derived indices the analyzer stamps). Exposing those would
+ * publish loader internals as a manifest surface, where they would be read,
+ * depended on, and then unchangeable.
+ *
+ * A DENYLIST rather than an allowlist, because the metadata vocabulary is
+ * deliberately open: a module may declare a field the standard library has never
+ * heard of, and an allowlist would silently hide it. The stamps, by contrast,
+ * are a closed set this repo controls — so the thing that can be enumerated is
+ * the thing enumerated.
+ */
+
+/** Fields written by the loader or the analyzer, not by the module's author. */
+export const DERIVED_METADATA_FIELDS: ReadonlySet<string> = new Set([
+  "source",
+  "sourceLine",
+  "module",
+  "moduleGlobals",
+  "exportedKinds",
+  "reExportedKinds",
+  "forwardedExport",
+]);
+
+/** The author-written half of a module doc's `metadata`. */
+export function authoredModuleMetadata(
+  metadata: Record<string, unknown> | undefined | null,
+): Record<string, unknown> {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return {};
+  const authored: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (DERIVED_METADATA_FIELDS.has(key)) continue;
+    authored[key] = value;
+  }
+  return authored;
+}
+
+/**
+ * The `module` namespace as a JSON Schema, or `undefined` when there is nothing
+ * to type it from.
+ *
+ * **One derivation, two consumers.** `cel-environment.ts` needs CEL type strings
+ * and `kernel-globals.ts` needs JSON Schema, and they used to reach the same
+ * conclusion through two hand-written ternary chains that had to agree forever
+ * about which values are open and which are closed. The schema is the richer of
+ * the two shapes, so it is what is derived; the CEL side converts with
+ * `jsonSchemaToCelType`, which every other namespace already goes through.
+ *
+ * Typed from the VALUES because a module doc's metadata is literals, not a
+ * schema map — the module a resource belongs to is fixed, so there is nothing to
+ * resolve.
+ *
+ * `undefined` means **open**, and the distinction matters in the rejecting
+ * direction: a set with no module doc must leave `module.*` unconstrained rather
+ * than close it over whatever metadata happened to be at hand, or a valid
+ * `module.version` becomes a hard error nobody can act on.
+ */
+export function moduleMetadataSchema(
+  metadata: Record<string, unknown> | undefined | null,
+): Record<string, any> | undefined {
+  const authored = authoredModuleMetadata(metadata);
+  const keys = Object.keys(authored);
+  if (keys.length === 0) return undefined;
+
+  const properties: Record<string, any> = {};
+  for (const key of keys) {
+    const value = authored[key];
+    properties[key] = Array.isArray(value)
+      ? { type: "array" }
+      : value !== null && typeof value === "object"
+        ? { type: "object", additionalProperties: true }
+        : {
+            type:
+              typeof value === "number"
+                ? "number"
+                : typeof value === "boolean"
+                  ? "boolean"
+                  : "string",
+          };
+  }
+  return { type: "object", properties, additionalProperties: false };
+}

package/src/parse-loaded-file.ts

@@ -7,6 +7,7 @@ import type { LoadedFile, ParseError } from "./loaded-types.js";
 import { migrateManifests, NO_MIGRATIONS } from "./migrations/driver.js";
 import type { MigrationEntry } from "./migrations/types.js";
 import { buildDocumentPositions } from "./position-metadata.js";
+import { expandManifestFragments } from "./manifest-schemas.js";
 import { precompileDoc } from "./precompile.js";
 import { documentToAst } from "./yaml-ast.js";
 
@@ -89,6 +90,21 @@ export function parseLoadedFile(
     ? migrateManifests({ source, manifests, entries: options.migrations })
     : NO_MIGRATIONS;
 
+  // Shared structural fragments (`telo://manifest#/$defs/InvokeStep`) are
+  // expanded for EVERY consumer, deliberately ungated.
+  //
+  // They are not authoring sugar the way `imports:` or a `!ref` tag is — they are
+  // the analyzer's own closed set, and nothing downstream is equipped to meet one
+  // unresolved: the editor's schema resolver handles document-local `#/` refs
+  // only and THROWS on anything else, so a gated expansion took every canvas that
+  // renders a `Run` step down. Round-tripping is unaffected because a save writes
+  // the YAML documents the editor holds separately (`saveModuleFromDocuments`),
+  // never a manifest object — so unlike `migrate`, no expansion here can reach an
+  // author's file.
+  for (const manifest of manifests) {
+    if (manifest) expandManifestFragments(manifest);
+  }
+
   let env: Environment | undefined;
   if (options?.compile) {
     for (let i = 0; i < manifests.length; i++) {

package/src/release/bump-level.ts

@@ -0,0 +1,95 @@
+/**
+ * The two vocabularies a release speaks, and the arithmetic between them.
+ *
+ * A **kind** is what an author writes in a fragment (`Added`, `Fixed`, …). It is
+ * changie's vocabulary, kept because it drives two things at once: the semantic
+ * level of the bump, and the heading the entry lands under in the changelog. A
+ * **level** is what the version arithmetic consumes.
+ *
+ * The mapping is the only place the two meet, and it is deliberately total: an
+ * unrecognized kind is refused rather than defaulted, because a typo that
+ * degraded to `patch` would silently under-release a breaking change.
+ */
+
+/** Semantic level of a version move. */
+export type BumpLevel = "major" | "minor" | "patch";
+
+/** Ordering used whenever several levels reach one module — the maximum wins,
+ *  because a module that inlines a breaking change is breaking for its own
+ *  consumers. */
+const LEVEL_RANK: Record<BumpLevel, number> = { patch: 0, minor: 1, major: 2 };
+
+export function maxLevel(a: BumpLevel, b: BumpLevel): BumpLevel {
+  return LEVEL_RANK[a] >= LEVEL_RANK[b] ? a : b;
+}
+
+/**
+ * Fragment kinds, in changelog section order, each with the level it induces.
+ *
+ * `Changed` / `Removed` induce `major`, which the pre-1.0 guard then rejects —
+ * they are kept in the vocabulary rather than dropped so the rejection can name
+ * what was written and say why, instead of reporting an unknown kind.
+ */
+export const FRAGMENT_KINDS = {
+  Added: "minor",
+  Changed: "major",
+  Deprecated: "minor",
+  Removed: "major",
+  Fixed: "patch",
+  Security: "patch",
+} as const satisfies Record<string, BumpLevel>;
+
+export type FragmentKind = keyof typeof FRAGMENT_KINDS;
+
+/** Declaration order, which is also the order sections appear in a changelog
+ *  release block. */
+export const FRAGMENT_KIND_ORDER: readonly FragmentKind[] = Object.keys(
+  FRAGMENT_KINDS,
+) as FragmentKind[];
+
+export function isFragmentKind(value: unknown): value is FragmentKind {
+  return typeof value === "string" && value in FRAGMENT_KINDS;
+}
+
+export function levelOfKind(kind: FragmentKind): BumpLevel {
+  return FRAGMENT_KINDS[kind];
+}
+
+/** A `major.minor.patch` triple. Pre-release and build metadata are not accepted:
+ *  a module version is the tag an artifact publishes under and the value a pin
+ *  resolves, and neither has a meaning for a suffix today. */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+
+export function isReleaseVersion(value: unknown): value is string {
+  return typeof value === "string" && VERSION.test(value);
+}
+
+/** Apply `level` to `version`. Throws on a version this system cannot represent,
+ *  rather than returning something plausible — every caller has already read the
+ *  value out of a manifest it is about to rewrite. */
+export function applyBump(version: string, level: BumpLevel): string {
+  const match = VERSION.exec(version);
+  if (!match) {
+    throw new Error(
+      `'${version}' is not a major.minor.patch version, so no ${level} bump can be derived from it.`,
+    );
+  }
+  const [major, minor, patch] = match.slice(1, 4).map(Number) as [number, number, number];
+  if (level === "major") return `${major + 1}.0.0`;
+  if (level === "minor") return `${major}.${minor + 1}.0`;
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+/** Numeric comparison, so `0.10.0` sorts after `0.9.0`. Returns a negative
+ *  number when `a` precedes `b`. An unparseable version sorts last rather than
+ *  throwing — this is used for display ordering, not for decisions. */
+export function compareVersions(a: string, b: string): number {
+  const pa = VERSION.exec(a);
+  const pb = VERSION.exec(b);
+  if (!pa || !pb) return pa ? -1 : pb ? 1 : a.localeCompare(b);
+  for (let i = 1; i <= 3; i++) {
+    const diff = Number(pa[i]) - Number(pb[i]);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}

package/src/release/changelog.ts

@@ -0,0 +1,62 @@
+/**
+ * Rendering a module's `CHANGELOG.md` entry, and splicing it into the file.
+ *
+ * The output shape is the one changie was configured to emit — `## <version> -
+ * <date>`, `### <Kind>`, `* <body>` — so a module's history stays one document
+ * across the handover rather than changing format mid-file.
+ *
+ * Prepending rather than rewriting: a changelog is append-only history, and the
+ * only edit ever made to it is inserting the newest release above the previous
+ * one. Everything already written is untouched bytes.
+ */
+
+import { FRAGMENT_KIND_ORDER, type FragmentKind } from "./bump-level.js";
+
+export const CHANGELOG_HEADER = "# Changelog";
+
+export interface ChangelogRelease {
+  readonly version: string;
+  /** `YYYY-MM-DD`. Passed in rather than read from a clock, so a plan renders
+   *  identically whenever it is rendered and a test needs no clock control. */
+  readonly date: string;
+  readonly entries: readonly { readonly kind: FragmentKind; readonly body: string }[];
+}
+
+/** One release block. Entries group under their kind, in the vocabulary's own
+ *  order, so two releases never disagree about where `Fixed` sits. */
+export function renderChangelogRelease(release: ChangelogRelease): string {
+  const byKind = new Map<FragmentKind, string[]>();
+  for (const entry of release.entries) {
+    const list = byKind.get(entry.kind);
+    if (list) list.push(entry.body);
+    else byKind.set(entry.kind, [entry.body]);
+  }
+
+  const lines = [`## ${release.version} - ${release.date}`];
+  for (const kind of FRAGMENT_KIND_ORDER) {
+    const bodies = byKind.get(kind);
+    if (!bodies) continue;
+    lines.push(`### ${kind}`);
+    for (const body of bodies) lines.push(`* ${body}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Insert a release block below the file's `# Changelog` header, creating the
+ * file's skeleton when it has none.
+ *
+ * A module with no changelog yet is the ordinary case for a new module, so this
+ * writes the header rather than failing — the alternative is a release that
+ * stops to ask for an empty file to be created by hand.
+ */
+export function prependChangelogRelease(existing: string | undefined, block: string): string {
+  const text = existing ?? "";
+  const header = text.match(/^#\s+Changelog[^\n]*\n/);
+  if (!header) {
+    const rest = text.trim();
+    return `${CHANGELOG_HEADER}\n\n${block}${rest ? `\n${rest}\n` : ""}`;
+  }
+  const after = text.slice(header[0].length).replace(/^\n+/, "");
+  return `${header[0]}\n${block}${after ? `\n${after}` : ""}`;
+}

package/src/release/fragment.ts

@@ -0,0 +1,130 @@
+/**
+ * A release fragment — one pending change, written by an author.
+ *
+ * The shape is changesets' (one file, several modules, one body) carrying
+ * changie's kind vocabulary, which is what lets one cross-cutting change be one
+ * file while the kind still drives both the level and the changelog section a
+ * line lands under. Changie's own file is the other arrangement — one module per
+ * file — so a change touching five modules meant five files repeating one
+ * sentence, and its key was the module's bare directory NAME, which two
+ * directories in different subtrees can share.
+ *
+ * A fragment names modules by **workspace-relative path**, the same key the
+ * ledger and every diagnostic use.
+ *
+ * They are plain YAML validated here, not a `Telo.*` kind: build-time repo state
+ * with no controller and no capability, which the runtime never loads.
+ */
+
+import { Document, parseDocument } from "yaml";
+import { isFragmentKind, type FragmentKind } from "./bump-level.js";
+
+/** A module's workspace-relative directory path — `modules/sql`, `apps/hub`. */
+export type ModuleKey = string;
+
+export interface ReleaseFragment {
+  /**
+   * Where this fragment was read from, workspace-relative. Carried so a
+   * diagnostic can name the file to fix and `apply` can delete the file it
+   * consumed.
+   */
+  readonly source: string;
+  /** The directly-changed modules this fragment declares, each with its kind. */
+  readonly modules: ReadonlyMap<ModuleKey, FragmentKind>;
+  /** The changelog line. */
+  readonly body: string;
+}
+
+export class FragmentError extends Error {
+  constructor(
+    readonly source: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function parseFragment(text: string, source: string): ReleaseFragment {
+  let value: unknown;
+  try {
+    value = parseDocument(text).toJSON();
+  } catch (err) {
+    throw new FragmentError(
+      source,
+      `${source} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new FragmentError(source, `${source} must be a YAML mapping.`);
+  }
+  const record = value as Record<string, unknown>;
+
+  for (const key of Object.keys(record)) {
+    if (key !== "modules" && key !== "body") {
+      throw new FragmentError(
+        source,
+        `${source}: unknown field '${key}'. A fragment carries 'modules:' and 'body:'.`,
+      );
+    }
+  }
+
+  const rawModules = record.modules;
+  if (rawModules === null || typeof rawModules !== "object" || Array.isArray(rawModules)) {
+    throw new FragmentError(
+      source,
+      `${source}: 'modules' must be a mapping of module path to kind, ` +
+        `e.g. { modules/sql: Fixed }.`,
+    );
+  }
+  const modules = new Map<ModuleKey, FragmentKind>();
+  for (const [key, kind] of Object.entries(rawModules as Record<string, unknown>)) {
+    if (!isFragmentKind(kind)) {
+      throw new FragmentError(
+        source,
+        `${source}: '${key}' declares kind '${String(kind)}', which is not a release kind. ` +
+          `Use Added, Changed, Deprecated, Removed, Fixed or Security.`,
+      );
+    }
+    modules.set(normalizeModuleKey(key), kind);
+  }
+  if (modules.size === 0) {
+    throw new FragmentError(
+      source,
+      `${source}: 'modules' is empty, so this fragment releases nothing. ` +
+        `Name at least one module by its workspace-relative path.`,
+    );
+  }
+
+  const body = record.body;
+  if (typeof body !== "string" || body.trim() === "") {
+    throw new FragmentError(
+      source,
+      `${source}: 'body' must be the changelog line for this change.`,
+    );
+  }
+
+  return { source, modules, body: body.trim() };
+}
+
+/**
+ * Render a fragment, for `telo release add`.
+ *
+ * Serialized rather than templated so a long body folds the way the YAML writer
+ * folds it, and so a module path needing quotes gets them.
+ */
+export function serializeFragment(
+  modules: ReadonlyMap<ModuleKey, FragmentKind>,
+  body: string,
+): string {
+  const doc = new Document({
+    modules: Object.fromEntries([...modules].map(([key, kind]) => [key, kind])),
+    body,
+  });
+  return doc.toString({ lineWidth: 88 });
+}
+
+/** Module keys are POSIX-separated and carry no leading `./` or trailing slash,
+ *  so the same directory written three ways is one key. */
+export function normalizeModuleKey(key: string): ModuleKey {
+  return key.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}

package/src/release/index.ts

@@ -0,0 +1,66 @@
+/**
+ * The release model: module identity, fragments, the ledger, the edge graph,
+ * level propagation and version planning.
+ *
+ * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * answer "what does changing this library bump?" from the same model the CLI
+ * releases from. Everything Node-shaped (finding the workspace, running the
+ * controller builder, building payloads, reading git, writing files) is
+ * `cli/nodejs/src/release/`.
+ */
+
+export {
+  FRAGMENT_KINDS,
+  FRAGMENT_KIND_ORDER,
+  applyBump,
+  compareVersions,
+  isFragmentKind,
+  isReleaseVersion,
+  levelOfKind,
+  maxLevel,
+} from "./bump-level.js";
+export type { BumpLevel, FragmentKind } from "./bump-level.js";
+
+export {
+  CHANGELOG_HEADER,
+  prependChangelogRelease,
+  renderChangelogRelease,
+} from "./changelog.js";
+export type { ChangelogRelease } from "./changelog.js";
+
+export { FragmentError, normalizeModuleKey, parseFragment, serializeFragment } from "./fragment.js";
+export type { ModuleKey, ReleaseFragment } from "./fragment.js";
+
+export { EMPTY_LEDGER, LEDGER_PATH, LedgerError, parseLedger, serializeLedger } from "./ledger.js";
+export type { Ledger, LedgerEntry } from "./ledger.js";
+
+export {
+  LOCALLY_DERIVED_LAYERS,
+  MANIFEST_LAYER,
+  diffLayerDigests,
+  layerDigestKey,
+} from "./payload-digest.js";
+export type { LayerChange, LayerDigests } from "./payload-digest.js";
+
+export { orderByImports, planRelease } from "./release-plan.js";
+export type {
+  ArtifactKind,
+  BumpReason,
+  ChangelogEntry,
+  ModuleEvidence,
+  PlannedModule,
+  ReleaseDiagnostic,
+  ReleaseEvidence,
+  ReleasePlan,
+} from "./release-plan.js";
+
+export {
+  VersionStampError,
+  readManifestVersion,
+  stampCrateVersion,
+  stampManifestVersion,
+  stampPackageVersion,
+} from "./version-stamp.js";
+
+export { WORKSPACE_FILENAME, WorkspaceConfigError, parseWorkspaceConfig } from "./workspace-config.js";
+export type { WorkspaceConfig } from "./workspace-config.js";