@fulmenhq/tsfulmen 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -12,6 +12,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No unreleased changes._
 
+---
+
+## [0.2.3] - 2026-01-28
+
+### Changed
+
+- **Vitest Upgrade** - Updated test framework from v2.1.9 to v4.0.18
+  - Resolves 70 Go stdlib CVEs in bundled esbuild binaries (dev/CI dependencies only)
+  - Critical vulnerabilities reduced from 6 to 0
+  - Test execution 32% faster (38s vs 56s)
+  - No breaking changes to test suite
+
+### Security
+
+- **CVE Remediation** - Eliminated critical Go 1.20.12 vulnerabilities in vite's nested esbuild
+  - Before: 94 findings (6 critical, 34 high, 54 medium)
+  - After: 24 findings (0 critical, 10 high, 14 medium)
+  - Remaining findings are recent 2025 CVEs in Go 1.25.5 (not legacy issues)
+  - **Note**: All vulnerabilities are in dev/CI tooling (esbuild binaries); production code surface has 0 findings
+
+---
+
+## [0.2.2] - 2026-01-28
+
+**Skipped** - Version number consumed by npm publish workflow reading local package.json before version bump completed. No package published to npm under this version.
+
+---
+
+## [0.2.1] - 2026-01-27
+
+### Changed
+
+- **Lifecycle Phase** - Project graduates from `alpha` to `beta` per Repository Lifecycle Standard
+  - 71% line coverage (above 60% beta threshold)
+  - Feature-complete modules with stable APIs
+  - Documentation kept current
+
+### Added
+
+- **Schema Multi-Dialect Support** - Meta-validation and compilation now supports JSON Schema drafts draft-04, draft-06, draft-07, draft-2019-09, and draft-2020-12
+  - Uses Crucible v0.4.9 meta catalog with bundled metaschemas and vocabulary schemas
+  - Dialect auto-detection from `$schema` declaration
+  - Per-dialect AJV instance caching for performance
+
+- **Improved Schema Validation** - `validateSchema()` now validates schemas against their declared `$schema` dialect (not just "can AJV compile it")
+  - Two-phase validation: meta-validation against dialect, then compilation check
+  - Better error messages for dialect-specific violations
+
+- **Fulencode Module** (`@fulmenhq/tsfulmen/fulencode`) - Canonical encoding/decoding facade
+  - **Core API**: `fulencode.encode()` / `fulencode.decode()` for consistent interface
+  - **Binary Encodings**: base64, base64url, base64_raw, hex, base32, base32hex
+  - **Text Encodings**: utf-8, utf-16le, utf-16be, iso-8859-1, ascii
+  - **Features**: padding control, line wrapping, whitespace handling, checksum computation (sha256, xxh3-128)
+  - **Error Handling**: Structured `FulencodeError` with operation context and error codes
+  - Standard entry point for future non-stdlib encodings
+
+### Changed
+
+- **Crucible SSOT** - Updated to v0.4.9
+  - Bundled JSON Schema metaschemas for offline validation
+  - Meta catalog with draft-04 through draft-2020-12 vocabulary schemas
+
+- **Test Coverage Improvements** - Overall coverage improved from 63.4% to 71.16%
+  - fulencode: 52.8% → 99.6% (+46.8%)
+  - fulpack: 41.7% → 72.5% (+30.8%)
+  - schema: 51.2% → 70.1% (+18.9%)
+  - pathfinder: 77.4% → 88.3% (+10.9%)
+
+---
+
 ## [0.2.0] - 2026-01-13
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 - **Cross-language parity**: Same exit codes, signals, and schemas as gofulmen, rsfulmen, pyfulmen
 - **Type-safe**: Full TypeScript types with strict mode throughout
 
-**Lifecycle Phase**: `stable` | **Version**: 0.2.0 | **Test Coverage**: 100%
+**Lifecycle Phase**: `beta` | **Version**: 0.2.3 | **Test Coverage**: 71%
 
 **Install**: `bun add @fulmenhq/tsfulmen` (or `npm install @fulmenhq/tsfulmen`)
 
@@ -27,6 +27,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 ## Features
 
 - ✅ **Error Handling** - Schema-backed FulmenError with severity levels (43 tests)
+- ✅ **Fulencode** - Canonical encoding/decoding facade for base64, hex, base32, and text formats (40+ tests)
 - ✅ **Telemetry & Metrics** - Counter/gauge/histogram with OTLP export (85 tests)
 - ✅ **Telemetry Instrumentation** - Metrics in config, schema, crucible modules (24 tests)
 - ✅ **HTTP Server Metrics** - Type-safe HTTP instrumentation with Express/Fastify/Bun middleware (40+ tests)
@@ -43,6 +44,7 @@ Every team writes their own HTTP status helpers, exit code enums, and country co
 - ✅ **Application Identity** - .fulmen/app.yaml discovery with caching and validation (93 tests)
 - ✅ **Pathfinder** - Filesystem traversal, repository root discovery with security boundaries, checksums, and observability (70 tests)
 - ✅ **Three-Layer Config Loading** - Defaults → User → Env pattern with schema validation (6 tests)
+- ✅ **Workhorse Control-Plane** - Config reload endpoint, control discovery, runtime info for service orchestration
 
 ## Installation
 
@@ -120,11 +122,12 @@ src/
 ├── crucible/    # 🚧 Crucible SSOT shim
 ├── errors/      # ✅ Error handling & propagation
 ├── foundry/     # ✅ Pattern catalogs, HTTP statuses, MIME detection
+├── fulencode/   # ✅ Canonical encoding/decoding (base64, hex, base32, text)
 ├── fulhash/     # ✅ Fast hashing with XXH3-128 and SHA-256
 ├── fulpack/     # ✅ Archive operations (TAR, TAR.GZ, ZIP, GZIP)
 ├── logging/     # ✅ Progressive logging with policy enforcement
 ├── pathfinder/  # ✅ Filesystem traversal with checksums and observability
-├── schema/      # ✅ Schema validation (AJV + CLI)
+├── schema/      # ✅ Schema validation (AJV + CLI, multi-dialect)
 └── telemetry/   # ✅ Metrics collection & export
 ```
 
@@ -268,6 +271,45 @@ const error = new FulmenError({
 });
 ```
 
+### Fulencode (Encoding/Decoding)
+
+Canonical encoding/decoding facade for binary and text formats:
+
+```typescript
+import { fulencode } from "@fulmenhq/tsfulmen/fulencode";
+
+// Encode binary to base64
+const encoded = await fulencode.encode(
+  new Uint8Array([72, 101, 108, 108, 111]),
+  "base64",
+);
+console.log(encoded.data); // "SGVsbG8="
+
+// Decode base64 to binary
+const decoded = await fulencode.decode("SGVsbG8=", "base64");
+console.log(new TextDecoder().decode(decoded.data)); // "Hello"
+
+// Hex encoding with checksum
+const hex = await fulencode.encode(data, "hex", {
+  hexCase: "upper",
+  computeChecksum: "sha256",
+});
+console.log(hex.data); // "48656C6C6F"
+console.log(hex.checksum); // "sha256:2cf24dba..."
+```
+
+**Supported Formats**:
+
+| Binary            | Text               |
+| ----------------- | ------------------ |
+| base64            | utf-8              |
+| base64url         | utf-16le, utf-16be |
+| base64_raw        | iso-8859-1, ascii  |
+| hex               |                    |
+| base32, base32hex |                    |
+
+**Features**: Padding control, line wrapping, whitespace handling, checksum computation (sha256, xxh3-128), structured `FulencodeError` with error codes.
+
 ### Telemetry & Metrics
 
 ```typescript
@@ -468,12 +510,15 @@ console.log(metadata.activeLayers); // ["defaults", "user", "env"]
 
 ### Schema Validation
 
+Multi-dialect JSON Schema validation supporting draft-04, draft-06, draft-07, draft-2019-09, and draft-2020-12:
+
 ```typescript
 import {
   getGlobalRegistry,
   compileSchemaById,
   validateDataBySchemaId,
   validateFileBySchemaId,
+  validateSchema,
   normalizeSchema,
 } from "@fulmenhq/tsfulmen/schema";
 
@@ -496,10 +541,19 @@ const fileResult = await validateFileBySchemaId(
   "./my-config.yaml",
 );
 
+// Validate a schema document against its declared dialect
+const schemaResult = await validateSchema({
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  properties: { name: { type: "string" } },
+});
+
 // Normalize schema for comparison
 const normalized = await normalizeSchema("./schema.yaml");
 ```
 
+**Supported Dialects**: draft-04, draft-06, draft-07, draft-2019-09, draft-2020-12. Dialect is auto-detected from the schema's `$schema` field (defaults to draft-2020-12).
+
 ### Schema Validation CLI (Developer Tool)
 
 TSFulmen includes a CLI for schema exploration and validation during development:
@@ -1131,12 +1185,12 @@ tsfulmen is licensed under MIT license - see [LICENSE](LICENSE) for complete det
 
 ## Status
 
-**Lifecycle Phase**: `alpha` ([Repository Lifecycle Standard](docs/crucible-ts/standards/repository-lifecycle.md))
+**Lifecycle Phase**: `beta` ([Repository Lifecycle Standard](docs/crucible-ts/standards/repository-lifecycle.md))
 
-- **Quality Bar**: 30% minimum test coverage (currently: 100%)
-- **Stability**: Early adopters; rapidly evolving features
-- **Breaking Changes**: Expected without deprecation warnings
-- **Documentation**: Major gaps documented; kept current
+- **Quality Bar**: 60% minimum test coverage (currently: 71%)
+- **Stability**: Feature-complete; stabilizing behavior
+- **Breaking Changes**: Addressed promptly with migration guidance
+- **Documentation**: Kept current
 
 See `LIFECYCLE_PHASE` file and [CHANGELOG.md](CHANGELOG.md) for version history.
 

package/config/crucible-ts/agentic/roles/README.md

@@ -2,7 +2,7 @@
 
 Baseline role prompts for AI agent sessions in the FulmenHQ ecosystem.
 
-**Schema**: [`role-prompt.schema.json`](../../../schemas/upstream/3leaps/agentic/v0/role-prompt.schema.json) (vendored from [3leaps/crucible](https://github.com/3leaps/crucible))
+**Schema**: [`role-prompt.schema.json`](../../../schemas/upstream/3leaps/crucible/schemas/agentic/v0/role-prompt.schema.json) (vendored from [3leaps/crucible](https://github.com/3leaps/crucible))
 
 ## Available Roles
 
@@ -48,13 +48,13 @@ Reference roles by slug in `AGENTS.md`:
 
 ## Schema Validation
 
-All role files conform to the [role-prompt schema](../../../schemas/upstream/3leaps/agentic/v0/role-prompt.schema.json).
+All role files conform to the [role-prompt schema](../../../schemas/upstream/3leaps/crucible/schemas/agentic/v0/role-prompt.schema.json).
 
 Validate with:
 
 ```bash
 # Using goneat
-goneat schema validate --schema schemas/upstream/3leaps/agentic/v0/role-prompt.schema.json config/agentic/roles/*.yaml
+goneat schema validate --schema schemas/upstream/3leaps/crucible/schemas/agentic/v0/role-prompt.schema.json config/agentic/roles/*.yaml
 ```
 
 ## Extending Roles

package/config/crucible-ts/library/fulencode/fixtures/README.md

@@ -0,0 +1,18 @@
+# Fulencode Fixtures
+
+These fixtures provide cross-language, deterministic inputs for Fulencode parity tests.
+
+Design goals:
+
+- ASCII-only source files; represent bytes as hex strings.
+- Small, stable fixtures; large/pathological payloads should be generated in tests.
+- Fixtures are SSOT and should not be duplicated in `lang/*` directories.
+
+Directory layout:
+
+- `valid-encodings/` - Known-good inputs/outputs for encode/decode
+- `invalid-encodings/` - Inputs that must trigger canonical errors
+- `normalization/` - Inputs/outputs for normalization profiles
+- `bom/` - BOM detection/removal cases
+- `detection/` - Minimal detection cases (BOM, UTF-8 validity, ASCII ambiguity)
+- `telemetry/` - Expected metric emissions for parity tests

package/config/crucible-ts/library/fulencode/fixtures/bom/bom.yaml

@@ -0,0 +1,14 @@
+version: "1.0"
+cases:
+  - name: "utf8-bom"
+    input_hex: "efbbbf48656c6c6f"
+    expected:
+      bom_type: "utf-8"
+      byte_length: 3
+      encoding_implied: "utf-8"
+  - name: "no-bom"
+    input_hex: "48656c6c6f"
+    expected:
+      bom_type: null
+      byte_length: 0
+      encoding_implied: null

package/config/crucible-ts/library/fulencode/fixtures/detection/detection.yaml

@@ -0,0 +1,12 @@
+version: "1.0"
+cases:
+  - name: "ascii-ambiguous"
+    input_hex: "48656c6c6f"
+    expected:
+      encoding: "utf-8"
+      level: "low"
+  - name: "utf8-bom-high"
+    input_hex: "efbbbf48656c6c6f"
+    expected:
+      encoding: "utf-8"
+      level: "high"

package/config/crucible-ts/library/fulencode/fixtures/invalid-encodings/base64.yaml

@@ -0,0 +1,10 @@
+version: "1.0"
+cases:
+  - name: "invalid-base64-character"
+    format: "base64"
+    encoded: "SGVsbG8*"
+    expected_error_code: "INVALID_ENCODING"
+  - name: "invalid-base64-padding"
+    format: "base64"
+    encoded: "SGVsbG8="
+    expected_error_code: "INVALID_ENCODING"

package/config/crucible-ts/library/fulencode/fixtures/normalization/text-safe.yaml

@@ -0,0 +1,10 @@
+version: "1.0"
+cases:
+  - name: "reject-zero-width"
+    profile: "text_safe"
+    input: "pay​pal.com"
+    expected_error_code: "ZERO_WIDTH_CHARACTER"
+  - name: "reject-bidi-override"
+    profile: "text_safe"
+    input: "abc‮def"
+    expected_error_code: "BIDI_CONTROL_CHARACTER"

package/config/crucible-ts/library/fulencode/fixtures/telemetry/telemetry-test-cases.yaml

@@ -0,0 +1,24 @@
+version: "1.0"
+cases:
+  - name: "decode-base64-success"
+    operation: "decode"
+    format: "base64"
+    result: "success"
+    expected_metrics:
+      - metric: "fulencode_operation_total"
+        tags:
+          operation: "decode"
+          format: "base64"
+          result: "success"
+        value: 1
+  - name: "detect-utf8-bom"
+    operation: "detect"
+    result: "success"
+    expected_metrics:
+      - metric: "fulencode_detect_result_total"
+        tags:
+          encoding: "utf-8"
+          confidence: "high"
+          result: "success"
+          source: "bom"
+        value: 1

package/config/crucible-ts/library/fulencode/fixtures/valid-encodings/base64.yaml

@@ -0,0 +1,11 @@
+version: "1.0"
+cases:
+  - name: "hello-world-base64"
+    format: "base64"
+    input_hex: "48656c6c6f2c20576f726c6421"
+    encoded: "SGVsbG8sIFdvcmxkIQ=="
+  - name: "hello-world-base64url-unpadded"
+    format: "base64url"
+    input_hex: "48656c6c6f2c20576f726c6421"
+    encoded: "SGVsbG8sIFdvcmxkIQ"
+    notes: "No padding, URL-safe alphabet"

package/config/crucible-ts/taxonomy/library/platform-modules/v1.0.0/modules.yaml

@@ -3,7 +3,7 @@
 # For reference data catalogs, see foundry-catalogs.yaml
 # Manually maintained but automatically validated
 version: "1.0.0"
-last_updated: "2025-11-15"
+last_updated: "2026-01-26"
 modules:
   # ============================================================================
   # CORE TIER - Always present, zero optional dependencies
@@ -301,7 +301,7 @@ modules:
     rationale: Widely useful reference data access; zero external dependencies
     evidence:
       has_schema: true
-      schema_path: schemas/library/foundry/v2.0.0/
+      schema_path: schemas/library/foundry/v1.0.0/
       has_config: true
       config_path: config/library/foundry/
     languages:

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

@@ -44,6 +44,19 @@ $defs:
       - fulhash_hash_string_total
       - fulhash_bytes_hashed_total
       - fulhash_operation_ms
+      - fulencode_operation_total
+      - fulencode_operation_duration_seconds
+      - fulencode_bytes_processed_total
+      - fulencode_expansion_ratio_percent
+      - fulencode_detect_result_total
+      - fulencode_detect_duration_seconds
+      - fulencode_normalize_total
+      - fulencode_normalize_semantic_changes_total
+      - fulencode_security_violations_total
+      - fulencode_corrections_total
+      - fulencode_bom_operations_total
+      - fulencode_bom_mismatches_total
+      - fulencode_errors_total
       - http_requests_total
       - http_request_duration_seconds
       - http_request_size_bytes
@@ -108,7 +121,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "0.4.8"
+version: "0.4.9"
 defaults:
   histogram_buckets:
     ms_metrics:
@@ -304,6 +317,71 @@ metrics:
     description: >
       Hash operation latency in milliseconds for all algorithms. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance benchmarking across XXH3-128 and SHA256.
 
+  - name: fulencode_operation_total
+    unit: count
+    description: >
+      Total Fulencode operations executed. Required tags: operation (encode|decode|detect|normalize|bom), result (success|error). Optional tags: format (bounded set from EncodingFormat).
+
+  - name: fulencode_operation_duration_seconds
+    unit: s
+    description: >
+      Fulencode operation duration in seconds. Histogram metric. Required tags: operation (encode|decode|detect|normalize|bom), result (success|error). Optional tags: format. Uses default seconds buckets.
+
+  - name: fulencode_bytes_processed_total
+    unit: bytes
+    description: >
+      Total bytes processed by Fulencode. Counter or histogram payloads are permitted depending on implementation. Required tags: operation (encode|decode), direction (in|out), result (success|error). Optional tags: format.
+
+  - name: fulencode_expansion_ratio_percent
+    unit: percent
+    description: >
+      Expansion ratio (output/input) expressed as a percentage for encode/decode operations. Histogram metric. Required tags: operation (encode|decode), result (success|error). Optional tags: format. Implementations MUST emit value as ratio*100 (e.g., 250 = 2.5x expansion).
+
+  - name: fulencode_detect_result_total
+    unit: count
+    description: >
+      Total encoding detection outcomes. Required tags: encoding (detected encoding or unknown), confidence (high|medium|low), result (success|error). Optional tags: source (bom|validation|heuristic|multibase).
+
+  - name: fulencode_detect_duration_seconds
+    unit: s
+    description: >
+      Encoding detection duration in seconds. Histogram metric. Required tags: result (success|error). Optional tags: sample_size_bucket (<1kb|1-10kb|10-100kb|>100kb). Uses default seconds buckets.
+
+  - name: fulencode_normalize_total
+    unit: count
+    description: >
+      Total normalization operations executed. Required tags: profile (nfc|nfd|nfkc|nfkd|custom profile name), result (success|error).
+
+  - name: fulencode_normalize_semantic_changes_total
+    unit: count
+    description: >
+      Total semantic changes detected during normalization (typically NFKC/NFKD). Required tags: profile (nfkc|nfkd), change_type (ligatures|superscripts_subscripts|roman_numerals|circled_numbers|enclosed_alphanumerics|fractions|other).
+
+  - name: fulencode_security_violations_total
+    unit: count
+    description: >
+      Total security violations detected by Fulencode. Required tags: type (invalid_utf8|invalid_utf16|encoding_bomb|excessive_combining|zero_width|bidi_controls|bom_mismatch|other), operation (encode|decode|detect|normalize|bom).
+
+  - name: fulencode_corrections_total
+    unit: count
+    description: >
+      Total corrections applied in non-strict modes (replace/fallback). Required tags: error_mode (replace|fallback|ignore), error_type (invalid_utf8|invalid_utf16|invalid_encoding|bom_mismatch|other).
+
+  - name: fulencode_bom_operations_total
+    unit: count
+    description: >
+      Total BOM operations executed. Required tags: operation (detect|remove|add|validate|correct), bom_type (utf-8|utf-16le|utf-16be|utf-32le|utf-32be|none), result (success|error).
+
+  - name: fulencode_bom_mismatches_total
+    unit: count
+    description: >
+      Total BOM mismatch events detected. Required tags: detected_bom, expected_encoding, action (error|fix|ignore).
+
+  - name: fulencode_errors_total
+    unit: count
+    description: >
+      Total Fulencode errors by canonical error code. Required tags: operation (encode|decode|detect|normalize|bom), code (canonical FulencodeError code).
+
   - name: http_requests_total
     unit: count
     description: >

package/dist/appidentity/index.d.ts

@@ -1,5 +1,7 @@
+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 { F as FulmenError } from '../fulmen-error-B_kX8jSC.js';
-import { b as SchemaValidationDiagnostic } from '../types-BJswWpQC.js';
+import { b as SchemaValidationDiagnostic } from '../types-DdoeE7F5.js';
 
 /**
  * Application Identity Constants
@@ -28,113 +30,6 @@ declare const APP_IDENTITY_SCHEMA_ID = "config/repository/app-identity/v1.0.0/ap
  */
 declare const MAX_ANCESTOR_SEARCH_DEPTH = 20;
 
-/**
- * Application Identity Types
- *
- * TypeScript interfaces matching the Crucible app-identity schema v1.0.0
- */
-/**
- * Repository category taxonomy from Fulmen standards
- */
-type RepositoryCategory = "cli" | "workhorse" | "service" | "library" | "pipeline" | "codex" | "sdk";
-/**
- * Python-specific packaging metadata
- * Field names use snake_case to match Crucible schema
- */
-interface PythonMetadata {
-    readonly distribution_name?: string;
-    readonly package_name?: string;
-    readonly console_scripts?: ReadonlyArray<{
-        readonly name: string;
-        readonly entry_point: string;
-    }>;
-}
-/**
- * Required application identity fields
- *
- * All fields are readonly to enforce immutability
- * Field names use snake_case to match Crucible schema
- */
-interface AppIdentity {
-    /**
-     * Lowercase kebab-case binary/executable name
-     * Pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$
-     */
-    readonly binary_name: string;
-    /**
-     * Lowercase alphanumeric vendor namespace (no hyphens)
-     * Pattern: ^[a-z][a-z0-9]{0,62}[a-z0-9]$
-     */
-    readonly vendor: string;
-    /**
-     * Uppercase environment variable prefix (must end with _)
-     * Pattern: ^[A-Z][A-Z0-9_]*_$
-     */
-    readonly env_prefix: string;
-    /**
-     * Filesystem-safe config directory name
-     * Pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$
-     */
-    readonly config_name: string;
-    /**
-     * One-line application description (10-200 chars)
-     */
-    readonly description: string;
-}
-/**
- * Optional metadata fields
- *
- * Additional properties are allowed for extensibility
- * Field names use snake_case to match Crucible schema
- */
-interface IdentityMetadata {
-    readonly project_url?: string;
-    readonly support_email?: string;
-    readonly license?: string;
-    readonly repository_category?: RepositoryCategory;
-    readonly telemetry_namespace?: string;
-    readonly registry_id?: string;
-    readonly python?: PythonMetadata;
-    readonly [key: string]: unknown;
-}
-/**
- * Complete application identity document
- */
-interface Identity {
-    readonly app: AppIdentity;
-    readonly metadata?: IdentityMetadata;
-}
-/**
- * Options for loading identity
- */
-interface LoadIdentityOptions {
-    /**
-     * Explicit path override
-     * Highest priority in discovery algorithm
-     */
-    readonly path?: string;
-    /**
-     * Test injection - bypass filesystem and discovery
-     * Never cached
-     */
-    readonly identity?: Identity;
-    /**
-     * Starting directory for ancestor search
-     * Defaults to process.cwd()
-     */
-    readonly startDir?: string;
-    /**
-     * Force reload, bypass cache
-     * Useful for testing cache behavior
-     */
-    readonly skipCache?: boolean;
-    /**
-     * Skip schema validation (dangerous)
-     * Only use for testing or when identity is pre-validated
-     */
-    readonly skipValidation?: boolean;
-}
-
 /**
  * Embedded Identity Registration
  *
@@ -383,4 +278,31 @@ declare function clearIdentityCache(): void;
  */
 declare function loadIdentity(options?: LoadIdentityOptions): Promise<Identity>;
 
-export { APP_IDENTITY_DIR, APP_IDENTITY_ENV_VAR, APP_IDENTITY_FILENAME, APP_IDENTITY_SCHEMA_ID, type AppIdentity, AppIdentityError, type ConfigIdentifiers, type Identity, type IdentityMetadata, type LoadIdentityOptions, MAX_ANCESTOR_SEARCH_DEPTH, type PythonMetadata, type RepositoryCategory, buildEnvVar, clearEmbeddedIdentity, clearIdentityCache, getBinaryName, getCachedIdentity, getConfigIdentifiers, getConfigName, getEmbeddedIdentity, getEnvPrefix, getEnvVar, getTelemetryNamespace, getVendor, hasEmbeddedIdentity, loadIdentity, registerEmbeddedIdentity };
+type RuntimeName = "bun" | "node" | "unknown";
+interface RuntimeInfo {
+    service: {
+        name: string;
+        vendor?: string;
+        version?: string;
+    };
+    runtime: {
+        name: RuntimeName;
+        version?: string;
+    };
+    platform: {
+        os: NodeJS.Platform;
+        arch: string;
+    };
+}
+interface BuildRuntimeInfoOptions {
+    identity?: Identity;
+    version?: string;
+    serviceName?: string;
+    vendor?: string;
+}
+/**
+ * Build a minimal runtime info payload suitable for discovery endpoints.
+ */
+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 };