@fulmenhq/tsfulmen 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -12,6 +12,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No unreleased changes._
 
+## [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.1 | **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)
@@ -120,11 +121,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 +270,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 +509,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 +540,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 +1184,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,5 @@
 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