@fulmenhq/tsfulmen 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -14,6 +14,56 @@ _No unreleased changes._
 
 ---
 
+## [0.4.0] - 2026-06-24
+
+> **Minor — compile-safe SSOT asset embedding.** Makes every bundled SSOT asset
+> (schemas, JSON-Schema metaschemas, foundry catalogs, telemetry taxonomy) resolve
+> without the filesystem, so tsfulmen works fully inside a `bun build --compile`
+> single-file binary — including standalone `serve`, schema discovery, and config
+> validation. No public API removals; the new surface is additive. Engine floor
+> unchanged (`>=22.12.0`). Full details in `docs/releases/v0.4.0.md`.
+
+### Added
+
+- **`@fulmenhq/tsfulmen/assets` — `AssetResolver` layer.** Central resolution for
+  bundled SSOT assets with two backends: `FsAssetResolver` (on-disk) and
+  `EmbeddedAssetResolver` (build-embedded generated modules). `resolveAssets()` /
+  `getAssetResolver()` select via `TSFULMEN_ASSET_MODE` (`auto` | `fs` | `embedded`;
+  default `auto` — filesystem when present, embedded otherwise). Logical paths are
+  package-root-relative and validated against path traversal.
+- **Embedded SSOT asset modules** (`src/assets/generated/`, checked in): per-domain
+  manifests (metaschema, schemas, foundry catalogs, taxonomy) so loads resolve with
+  no filesystem read in a compiled binary. Regenerated via `make embed-assets`;
+  drift-guarded by `make verify-embedded-assets` (in `check-all`).
+- **Compile-safety guards** (CI-enforced): `verify-embedded-compile` (in-binary
+  read/enumerate **and** standalone `serve` from a temp cwd) and
+  `verify-dist-asset-partition` (public entries stay lean; corpus in exactly one
+  shared chunk; per-domain presence + size report).
+
+### Changed
+
+- **All SSOT asset loads now route through the `AssetResolver`** — schema registry
+  discovery, validator metaschemas/vocabulary/`compileSchemaById`/cross-tree `$ref`
+  resolution, foundry catalogs + signals catalog, and telemetry taxonomy — replacing
+  `import.meta.url`/`__dirname`-relative `readFile`. `SchemaMetadata.path` is now a
+  logical (resolver-relative) path. Fixes latent cwd/layout fragility in addition to
+  enabling compile-safety.
+- **Build emits shared chunks** (`tsup splitting: true`): the embedded corpus is
+  deduped into one shared chunk rather than duplicated per entry, and public entry
+  files stay lean. The full `dist/` tree drops to ~3.7 MB vs ~24 MB (~1.1 MB of that
+  is JS across all entries plus one shared corpus chunk; the rest is type declarations
+  and source maps). Published `dist/` now includes `chunk-*.js` (packed automatically
+  via `files: ["dist"]`).
+- **Synced Crucible SSOT `v0.4.14 → v0.4.15`** — fixes cross-schema `$ref`/`$id`
+  vs. file-layout inconsistencies (observability/logging `$id` version-as-directory;
+  module-manifest relative-ref correction) surfaced by the resolver repoint.
+
+### Fixed
+
+- **Standalone `serve`, schema discovery, and config validation work in
+  `bun build --compile` single-file binaries** — the foundry signals catalog and the
+  rest of the SSOT assets are no longer read from an absent on-disk tree.
+
 ## [0.3.3] - 2026-06-17
 
 > **Patch — compile-safety ergonomics.** Two purely-additive API options that let `bun --compile` single-file binary consumers register a build-embedded identity and load embedded config without per-consumer workarounds — ahead of the larger v0.4.0 SSOT-asset-embedding work. No breaking changes; the existing exported `LoadConfigOptions` shape is unchanged; engine floor unchanged (`>=22.12.0`). Full details in `docs/releases/v0.3.3.md`.
@@ -43,7 +93,7 @@ _No unreleased changes._
 
 ### Fixed
 
-- **CLI shadowing under `bun build --compile`** (#15) — the schema/signals/prometheus CLIs self-executed on import via the non-compile-safe guard `import.meta.url === \`file://${process.argv[1]}\``; under `--compile` it fired for non-entry modules, so a compiled consumer importing `@fulmenhq/tsfulmen/schema` ran `tsfulmen-schema` instead of its own program. The library modules no longer parse argv on import; executables moved to dedicated bin entries out of the importable graph.
+- **CLI shadowing under `bun build --compile`** (#15) — the schema/signals/prometheus CLIs self-executed on import via a non-compile-safe main-module guard comparing `import.meta.url` to `process.argv[1]`; under `--compile` it fired for non-entry modules, so a compiled consumer importing `@fulmenhq/tsfulmen/schema` ran `tsfulmen-schema` instead of its own program. The library modules no longer parse argv on import; executables moved to dedicated bin entries out of the importable graph.
 - **Compiled-binary WASM `ENOENT` crash** (#14) — bump `@3leaps/string-metrics-wasm` 0.3.8 → 0.3.10, fixing the eager top-level WASM load that `--compile` rewrites but does not embed. Consumers no longer need an `overrides` entry.
 
 ### Added

package/README.md

@@ -5,10 +5,11 @@
 Every team writes their own HTTP status helpers, exit code enums, and country code lookups. tsfulmen provides production-grade TypeScript implementations derived from a single source of truth—so your TypeScript/Node.js services use the same codes as your Go, Rust, and Python services.
 
 - **Zero runtime network calls**: All catalogs embedded at build time
+- **Compile-safe**: Schemas, foundry catalogs, and standalone metrics `serve` resolve with no filesystem, so the full SDK runs inside a `bun build --compile` single-file binary
 - **Cross-language parity**: Same exit codes, signals, and schemas as gofulmen, rsfulmen, pyfulmen
 - **Type-safe**: Full TypeScript types with strict mode throughout
 
-**Lifecycle Phase**: `beta` | **Version**: 0.3.0 | **Test Coverage**: 71%
+**Lifecycle Phase**: `beta` | **Version**: 0.4.0 | **Test Coverage**: 71%
 
 **Install**: `bun add @fulmenhq/tsfulmen` (or `npm install @fulmenhq/tsfulmen`)
 
@@ -38,6 +39,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 - ✅ **DocScribe** - Document processing with frontmatter parsing (50+ tests)
 - ✅ **Config Path API** - XDG-compliant configuration directory resolution (26 tests)
 - ✅ **Schema Validation** - JSON Schema 2020-12 validation with AJV and CLI (115 tests)
+- ✅ **Compile-Safe Assets** - SSOT schemas, foundry catalogs, and telemetry taxonomy resolve with no filesystem (`AssetResolver` + `TSFULMEN_ASSET_MODE`), so schema validation and standalone `serve` run inside a `bun --compile` single-file binary
 - ✅ **Foundry Module** - Pattern catalogs, HTTP statuses, MIME detection, similarity (278 tests)
 - ✅ **Exit Codes** - Standardized process exit codes with simplified modes and platform detection (34 tests)
 - ✅ **Signal Handling** - Cross-platform signal handling with graceful shutdown and Windows fallback (180 tests)
@@ -196,6 +198,33 @@ process.chdir(repoRoot);
 
 See `docs/guides/crucible-assets.md` for deeper guidance.
 
+### Compile-Safe Assets & Single-File Binaries (v0.4.0)
+
+tsfulmen resolves its bundled SSOT assets — JSON Schemas, metaschemas, foundry catalogs, and the telemetry taxonomy — through a single `AssetResolver` with filesystem and build-embedded backends. This makes the full SDK (schema validation, foundry catalogs, and standalone metrics `serve`) work inside a `bun build --compile` single-file binary, where no asset tree exists on disk.
+
+```typescript
+import { getAssetResolver } from "@fulmenhq/tsfulmen/assets";
+
+const resolver = getAssetResolver(); // auto: filesystem when present, embedded otherwise
+const signals = await resolver.read(
+  "config/crucible-ts/library/foundry/signals.yaml",
+);
+const schemas = await resolver.list(["schemas/crucible-ts/**/*.schema.json"]);
+```
+
+If you consume tsfulmen normally (npm / `node dist`), there is nothing to do — the default `auto` mode reads the on-disk asset trees. Building a compiled binary needs no special flags; the embedded modules are bundled automatically:
+
+```bash
+bun build --compile ./your-app.ts --outfile your-app
+./your-app serve     # signals catalog + metrics server resolve from embedded assets
+```
+
+Force a backend with `TSFULMEN_ASSET_MODE` (`auto` | `fs` | `embedded`) when you need to (e.g. testing the embedded path locally).
+
+> **Operator note**: the metrics `serve` HTTP server binds `127.0.0.1` (loopback) by default. Keep loopback unless you intentionally bind publicly (`--host 0.0.0.0`), in which case front it with authentication / rate-limiting.
+
+See [Compile-safe SSOT assets](docs/development/compile-safe-assets.md) for the full guide.
+
 ### Application Identity
 
 Load application identity from `.fulmen/app.yaml` for vendor/app-specific configuration:

package/config/crucible-ts/taxonomy/metrics.yaml

@@ -121,7 +121,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "0.4.14"
+version: "0.4.15"
 defaults:
   histogram_buckets:
     ms_metrics: