@telorun/analyzer 0.59.0 → 0.61.0

package/dist/module-library.js

@@ -0,0 +1,162 @@
+/**
+ * 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, } from "./artifact-selector.js";
+/** Every key an entry may carry: the two locators, plus the selector axes. */
+const KNOWN_KEYS = new Set(["specifier", "path", "source", "format", ...PLATFORM_AXES]);
+/** Normalize a `path` / `source` value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value) {
+    return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+function requiredString(entry, key) {
+    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) {
+    const declared = ownerJson?.exports?.code;
+    const candidates = [];
+    const problems = [];
+    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;
+        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;
+        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/dist/module-metadata-scope.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare const DERIVED_METADATA_FIELDS: ReadonlySet<string>;
+/** The author-written half of a module doc's `metadata`. */
+export declare function authoredModuleMetadata(metadata: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/**
+ * 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 declare function moduleMetadataSchema(metadata: Record<string, unknown> | undefined | null): Record<string, any> | undefined;
+//# sourceMappingURL=module-metadata-scope.d.ts.map

package/dist/module-metadata-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-metadata-scope.d.ts","sourceRoot":"","sources":["../src/module-metadata-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAQtD,CAAC;AAEH,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACnD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACnD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC"}

package/dist/module-metadata-scope.js

@@ -0,0 +1,82 @@
+/**
+ * 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 = new Set([
+    "source",
+    "sourceLine",
+    "module",
+    "moduleGlobals",
+    "exportedKinds",
+    "reExportedKinds",
+    "forwardedExport",
+]);
+/** The author-written half of a module doc's `metadata`. */
+export function authoredModuleMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return {};
+    const authored = {};
+    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) {
+    const authored = authoredModuleMetadata(metadata);
+    const keys = Object.keys(authored);
+    if (keys.length === 0)
+        return undefined;
+    const properties = {};
+    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/dist/parse-loaded-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA2DZ"}
+{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA0EZ"}

package/dist/parse-loaded-file.js

@@ -3,6 +3,7 @@ import { parseAllDocuments } from "yaml";
 import { buildCelEnvironment } from "./cel-environment.js";
 import { migrateManifests, NO_MIGRATIONS } from "./migrations/driver.js";
 import { buildDocumentPositions } from "./position-metadata.js";
+import { expandManifestFragments } from "./manifest-schemas.js";
 import { precompileDoc } from "./precompile.js";
 import { documentToAst } from "./yaml-ast.js";
 /** Append an actionable hint to raw yaml-parser messages that are otherwise
@@ -57,6 +58,21 @@ export function parseLoadedFile(source, requestedUrl, text, options) {
     const migrations = options?.migrate
         ? 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;
     if (options?.compile) {
         for (let i = 0; i < manifests.length; i++) {

package/dist/release/bump-level.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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";
+export declare function maxLevel(a: BumpLevel, b: BumpLevel): BumpLevel;
+/**
+ * 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 declare const FRAGMENT_KINDS: {
+    readonly Added: "minor";
+    readonly Changed: "major";
+    readonly Deprecated: "minor";
+    readonly Removed: "major";
+    readonly Fixed: "patch";
+    readonly Security: "patch";
+};
+export type FragmentKind = keyof typeof FRAGMENT_KINDS;
+/** Declaration order, which is also the order sections appear in a changelog
+ *  release block. */
+export declare const FRAGMENT_KIND_ORDER: readonly FragmentKind[];
+export declare function isFragmentKind(value: unknown): value is FragmentKind;
+export declare function levelOfKind(kind: FragmentKind): BumpLevel;
+export declare function isReleaseVersion(value: unknown): value is string;
+/** 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 declare function applyBump(version: string, level: BumpLevel): string;
+/** 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 declare function compareVersions(a: string, b: string): number;
+//# sourceMappingURL=bump-level.d.ts.map

package/dist/release/bump-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bump-level.d.ts","sourceRoot":"","sources":["../../src/release/bump-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wCAAwC;AACxC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAOpD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAE9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;CAOmB,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,cAAc,CAAC;AAEvD;qBACqB;AACrB,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAEpC,CAAC;AAEpB,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAEzD;AAOD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;sDAEsD;AACtD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAWnE;AAED;;uEAEuE;AACvE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5D"}

package/dist/release/bump-level.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/** 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 = { patch: 0, minor: 1, major: 2 };
+export function maxLevel(a, b) {
+    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",
+};
+/** Declaration order, which is also the order sections appear in a changelog
+ *  release block. */
+export const FRAGMENT_KIND_ORDER = Object.keys(FRAGMENT_KINDS);
+export function isFragmentKind(value) {
+    return typeof value === "string" && value in FRAGMENT_KINDS;
+}
+export function levelOfKind(kind) {
+    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) {
+    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, level) {
+    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);
+    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, b) {
+    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/dist/release/changelog.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { type FragmentKind } from "./bump-level.js";
+export declare 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 declare function renderChangelogRelease(release: ChangelogRelease): string;
+/**
+ * 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 declare function prependChangelogRelease(existing: string | undefined, block: string): string;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/release/changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/release/changelog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEzE,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;iFAC6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACrF;AAED;sEACsE;AACtE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAgBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS3F"}

package/dist/release/changelog.js

@@ -0,0 +1,53 @@
+/**
+ * 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 } from "./bump-level.js";
+export const CHANGELOG_HEADER = "# Changelog";
+/** 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) {
+    const byKind = new Map();
+    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, block) {
+    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/dist/release/fragment.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { 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 declare class FragmentError extends Error {
+    readonly source: string;
+    constructor(source: string, message: string);
+}
+export declare function parseFragment(text: string, source: string): ReleaseFragment;
+/**
+ * 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 declare function serializeFragment(modules: ReadonlyMap<ModuleKey, FragmentKind>, body: string): string;
+/** Module keys are POSIX-separated and carry no leading `./` or trailing slash,
+ *  so the same directory written three ways is one key. */
+export declare function normalizeModuleKey(key: string): ModuleKey;
+//# sourceMappingURL=fragment.d.ts.map

package/dist/release/fragment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment.d.ts","sourceRoot":"","sources":["../../src/release/fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpE,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACvD,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM;CAIlB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CA4D3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,YAAY,CAAC,EAC7C,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED;2DAC2D;AAC3D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAEzD"}