@fulmenhq/tsfulmen 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -14,6 +14,70 @@ _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`.
+
+### Added
+
+- **`skipValidation` on `registerEmbeddedIdentity(data, options?)`** — symmetric with the existing `loadIdentity({ skipValidation })`. Lets a `bun --compile` binary register a CI-validated embedded identity without hitting the filesystem-backed schema registry (absent in a single-file binary). Parse / first-wins / deep-freeze semantics are unchanged; only schema validation is gated. New `RegisterEmbeddedIdentityOptions` type exported from `appidentity`.
+- **Inline `defaults` / `schema` on `loadConfig`** — provide a pre-parsed `defaults` object and/or an inline `schema` string instead of file paths, so consumers embedding config at build time needn't write content to a temp file just to pass a path. Exposed via a new `LoadInlineConfigOptions` shape and a `loadConfig` overload; `defaults` is `structuredClone`'d so callers' embedded objects are never mutated.
+
+### Changed
+
+- **`loadConfig` options split into path-based and inline shapes** (additive). `LoadConfigOptions` keeps `defaultsPath: string` (required) exactly as before; the new `LoadInlineConfigOptions` carries `defaults` (required). Both extend a shared `BaseLoadConfigOptions` and are mutually exclusive at the type level (`?: never`); `loadConfig` is overloaded over the two. The existing exported `LoadConfigOptions` is unchanged — patch-compatible for strict TypeScript consumers.
+- **`ConfigMetadata` diagnostics** — adds optional `defaultsSource: "path" | "inline"` and `schema.source: "path" | "inline" | null`. `defaultsPath` stays typed `string` (reports `""` for inline). Fixes a bug where, when both inline `schema` and `schemaPath` were given, `schema.path` mis-reported the unused `schemaPath` — inline now correctly reports `path: null`.
+
 ## [0.3.2] - 2026-06-17
 
 > **Patch — app-identity follow-up.** Syncs the Crucible SSOT to v0.4.14 (which adds the formal `metadata.typescript` app-identity section) and promotes tsfulmen's interim custom `metadata.console_scripts` field to it. No code or behavior change; the only published delta is the refreshed bundled `crucible-ts` schemas. Full details in `docs/releases/v0.3.2.md`.
@@ -29,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:

package/dist/appidentity/index.d.ts

@@ -1,5 +1,5 @@
-import { I as Identity, L as LoadIdentityOptions } from '../types-Dv5TERCM.js';
-export { A as AppIdentity, a as IdentityMetadata, P as PythonMetadata, R as RepositoryCategory } from '../types-Dv5TERCM.js';
+import { I as Identity, R as RegisterEmbeddedIdentityOptions, L as LoadIdentityOptions } from '../types-CHDvDRCf.js';
+export { A as AppIdentity, a as IdentityMetadata, P as PythonMetadata, b as RepositoryCategory } from '../types-CHDvDRCf.js';
 import { F as FulmenError } from '../fulmen-error-B_kX8jSC.js';
 import { b as SchemaValidationDiagnostic } from '../types-DdoeE7F5.js';
 
@@ -50,10 +50,11 @@ declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
  *
  * Semantics:
  * - First registration wins (subsequent calls throw error)
- * - Validates against schema on registration
+ * - Validates against schema on registration (unless `skipValidation`)
  * - Stores as immutable process-level fallback
  *
  * @param data - YAML string or pre-parsed Identity object
+ * @param options - Optional registration options (see {@link RegisterEmbeddedIdentityOptions})
  * @throws {AppIdentityError} If already registered or validation fails
  *
  * @example
@@ -75,8 +76,17 @@ declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
  *   // Embedded identity not available - discovery will use filesystem
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // In a `bun --compile` single-file binary, the FS-backed schema registry
+ * // is unavailable. Register a build-time-embedded, CI-validated identity
+ * // without re-validating against the (absent) schema registry:
+ * import embeddedYaml from "./app-identity.embedded.js"; // inlined at build
+ * registerEmbeddedIdentity(embeddedYaml, { skipValidation: true });
+ * ```
  */
-declare function registerEmbeddedIdentity(data: string | Identity): Promise<void>;
+declare function registerEmbeddedIdentity(data: string | Identity, options?: RegisterEmbeddedIdentityOptions): Promise<void>;
 /**
  * Check if embedded identity has been registered
  *
@@ -305,4 +315,4 @@ interface BuildRuntimeInfoOptions {
  */
 declare function buildRuntimeInfo(options?: BuildRuntimeInfoOptions): RuntimeInfo;
 
-export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, AppIdentityError, type BuildRuntimeInfoOptions, type ConfigIdentifiers, Identity, LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type RuntimeInfo, type RuntimeName, buildEnvVar, buildRuntimeInfo, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };
+export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, AppIdentityError, type BuildRuntimeInfoOptions, type ConfigIdentifiers, Identity, LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, RegisterEmbeddedIdentityOptions, type RuntimeInfo, type RuntimeName, buildEnvVar, buildRuntimeInfo, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };