@fulmenhq/tsfulmen 0.2.0 → 0.2.2

package/dist/{types-BJswWpQC.d.ts → types-DdoeE7F5.d.ts}

@@ -113,7 +113,7 @@ interface SchemaRegistryOptions {
 /**
  * Schema input types
  */
-type SchemaInput = string | Buffer | Record<string, unknown>;
+type SchemaInput = string | Buffer | boolean | Record<string, unknown>;
 /**
  * Schema source information
  */

package/package.json

@@ -3,6 +3,7 @@
   "dependencies": {
     "@3leaps/string-metrics-wasm": "0.3.8",
     "ajv": "^8.17.1",
+    "ajv-draft-04": "^1.0.0",
     "ajv-formats": "^3.0.1",
     "archiver": "^7.0.1",
     "commander": "^14.0.1",
@@ -23,7 +24,7 @@
     "@types/node": "^22.9.0",
     "@types/picomatch": "^4.0.2",
     "@types/unzipper": "^0.10.11",
-    "@vitest/coverage-v8": "^4.0.7",
+    "@vitest/coverage-v8": "^2.1.5",
     "@vitest/ui": "^2.1.5",
     "fastify": "^5.2.0",
     "prettier": "^3.6.2",
@@ -74,6 +75,10 @@
       "import": "./dist/foundry/similarity/index.js",
       "types": "./dist/foundry/similarity/index.d.ts"
     },
+    "./fulencode": {
+      "import": "./dist/fulencode/index.js",
+      "types": "./dist/fulencode/index.d.ts"
+    },
     "./fulhash": {
       "import": "./dist/fulhash/index.js",
       "types": "./dist/fulhash/index.d.ts"
@@ -179,5 +184,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.2.0"
+  "version": "0.2.2"
 }

package/schemas/crucible-ts/library/fulencode/v1.0.0/README.md

@@ -0,0 +1,37 @@
+# Fulencode Schemas (v1.0.0)
+
+These schemas define the SSOT contracts for the Fulencode module.
+
+Fulencode is an opt-in (Specialized-tier) facade that standardizes encoding/decoding, text encoding validation/detection, Unicode normalization, BOM handling, and security limits across Fulmen helper libraries.
+
+## Files
+
+- `fulencode-config.schema.json` - Module configuration (limits + defaults).
+
+Method option schemas:
+
+- `encode-options.schema.json`
+- `decode-options.schema.json`
+- `detect-options.schema.json`
+- `normalize-options.schema.json`
+
+Result payload schemas:
+
+- `encoding-result.schema.json`
+- `decoding-result.schema.json`
+- `detection-result.schema.json`
+- `normalization-result.schema.json`
+- `bom-result.schema.json`
+
+Error envelope:
+
+- `fulencode-error.schema.json`
+
+## Related SSOT (Taxonomies + Standard)
+
+- Standard: `docs/standards/library/modules/fulencode.md`
+- Encoding formats taxonomy: `schemas/taxonomy/library/fulencode/encoding-families/v1.0.0/families.yaml`
+- Normalization profiles taxonomy: `schemas/taxonomy/library/fulencode/normalization-profiles/v1.0.0/profiles.yaml`
+- Detection confidence taxonomy: `schemas/taxonomy/library/fulencode/detection-confidence/v1.0.0/levels.yaml`
+
+These schemas validate data structures produced by helper libraries and support cross-language parity fixtures.

package/schemas/crucible-ts/library/fulencode/v1.0.0/bom-result.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/bom-result.schema.json",
+  "title": "Fulencode BOM Result",
+  "description": "Result payload for fulencode BOM detection",
+  "type": "object",
+  "properties": {
+    "bom_type": {
+      "description": "Detected BOM type or null when none.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "utf-8",
+            "utf-16le",
+            "utf-16be",
+            "utf-32le",
+            "utf-32be"
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "byte_length": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "encoding_implied": {
+      "description": "Encoding implied by the BOM when present.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "bom_type",
+    "byte_length",
+    "encoding_implied"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/decode-options.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/decode-options.schema.json",
+  "title": "Fulencode Decode Options",
+  "description": "Options for fulencode decode() operation",
+  "type": "object",
+  "properties": {
+    "verify_checksum": {
+      "type": "boolean",
+      "description": "Verify embedded checksum when present."
+    },
+    "compute_checksum": {
+      "type": "string",
+      "description": "Checksum algorithm to compute on decoded output.",
+      "enum": [
+        "xxh3-128",
+        "sha256",
+        "sha512",
+        "sha1",
+        "md5"
+      ]
+    },
+    "max_decoded_size": {
+      "type": "integer",
+      "description": "Maximum decoded output size in bytes.",
+      "minimum": 1024
+    },
+    "max_expansion_ratio": {
+      "type": "number",
+      "description": "Maximum decode expansion ratio (encoding bomb protection).",
+      "minimum": 1.0
+    },
+    "on_error": {
+      "type": "string",
+      "description": "Error handling mode.",
+      "enum": [
+        "strict",
+        "replace",
+        "ignore",
+        "fallback"
+      ]
+    },
+    "fallback_formats": {
+      "type": "array",
+      "description": "Fallback formats to attempt when on_error is fallback.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ignore_whitespace": {
+      "type": "boolean",
+      "description": "Ignore ASCII whitespace in encoded input when supported."
+    },
+    "validate_padding": {
+      "type": "boolean",
+      "description": "Require correct padding when supported."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/decoding-result.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/decoding-result.schema.json",
+  "title": "Fulencode Decoding Result",
+  "description": "Result payload for fulencode decode()",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 255
+      }
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "base64",
+        "base64url",
+        "base64_raw",
+        "base32",
+        "base32hex",
+        "hex",
+        "utf-8",
+        "utf-16le",
+        "utf-16be",
+        "iso-8859-1",
+        "cp1252",
+        "ascii"
+      ]
+    },
+    "input_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checksum": {
+      "type": "string"
+    },
+    "checksum_verified": {
+      "type": "boolean"
+    },
+    "checksum_algorithm": {
+      "type": "string"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "corrections_applied": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "data",
+    "format",
+    "input_size",
+    "output_size",
+    "warnings",
+    "corrections_applied"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/detect-options.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/detect-options.schema.json",
+  "title": "Fulencode Detect Options",
+  "description": "Options for fulencode detect() operation",
+  "type": "object",
+  "properties": {
+    "max_sample_size": {
+      "type": "integer",
+      "description": "Maximum bytes to analyze.",
+      "minimum": 32
+    },
+    "min_confidence": {
+      "type": "number",
+      "description": "Minimum confidence threshold for a non-error detection result.",
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "recognize_multibase": {
+      "type": "boolean",
+      "description": "Recognize multibase prefixes (detection only; encoding may require extension module)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/detection-result.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/detection-result.schema.json",
+  "title": "Fulencode Detection Result",
+  "description": "Result payload for fulencode detect()",
+  "type": "object",
+  "properties": {
+    "encoding": {
+      "description": "Detected encoding or null when unknown.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "level": {
+      "type": "string",
+      "enum": [
+        "high",
+        "medium",
+        "low"
+      ]
+    },
+    "multibase_prefix": {
+      "description": "Detected multibase prefix if present.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "encoding",
+    "confidence",
+    "level",
+    "warnings"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/encode-options.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/encode-options.schema.json",
+  "title": "Fulencode Encode Options",
+  "description": "Options for fulencode encode() operation",
+  "type": "object",
+  "properties": {
+    "padding": {
+      "type": "boolean",
+      "description": "Enable/disable padding when supported (Base64/Base32)."
+    },
+    "case": {
+      "type": "string",
+      "description": "Hex output case.",
+      "enum": [
+        "upper",
+        "lower"
+      ]
+    },
+    "line_length": {
+      "description": "Optional line wrap length for text output.",
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 1
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "line_ending": {
+      "type": "string",
+      "description": "Line ending to use when line wrapping.",
+      "enum": [
+        "\n",
+        "\r\n"
+      ]
+    },
+    "max_encoded_size": {
+      "type": "integer",
+      "description": "Maximum encoded output size in bytes.",
+      "minimum": 1024
+    },
+    "compute_checksum": {
+      "type": "string",
+      "description": "Checksum algorithm to compute on encoded output.",
+      "enum": [
+        "xxh3-128",
+        "sha256",
+        "sha512",
+        "sha1",
+        "md5"
+      ]
+    },
+    "embed_checksum": {
+      "type": "boolean",
+      "description": "Whether to embed checksum alongside encoded output (implementation-defined framing)."
+    },
+    "on_error": {
+      "type": "string",
+      "description": "Error handling mode when encoding text inputs.",
+      "enum": [
+        "strict",
+        "replace",
+        "ignore"
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/encoding-result.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/encoding-result.schema.json",
+  "title": "Fulencode Encoding Result",
+  "description": "Result payload for fulencode encode()",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "string"
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "base64",
+        "base64url",
+        "base64_raw",
+        "base32",
+        "base32hex",
+        "hex",
+        "utf-8",
+        "utf-16le",
+        "utf-16be",
+        "iso-8859-1",
+        "cp1252",
+        "ascii"
+      ]
+    },
+    "input_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checksum": {
+      "type": "string"
+    },
+    "checksum_algorithm": {
+      "type": "string"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "data",
+    "format",
+    "input_size",
+    "output_size",
+    "warnings"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/fulencode-config.schema.json

@@ -33,7 +33,8 @@
           "minimum": 1,
           "maximum": 100
         }
-      }
+      },
+      "additionalProperties": false
     },
     "defaults": {
       "type": "object",
@@ -66,7 +67,8 @@
           "description": "Default normalization profile",
           "default": "nfc"
         }
-      }
+      },
+      "additionalProperties": false
     },
     "detection": {
       "type": "object",
@@ -84,7 +86,9 @@
           "default": 8192,
           "minimum": 32
         }
-      }
+      },
+      "additionalProperties": false
     }
-  }
+  },
+  "additionalProperties": false
 }

package/schemas/crucible-ts/library/fulencode/v1.0.0/fulencode-error.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/fulencode-error.schema.json",
+  "title": "Fulencode Error",
+  "description": "Canonical error envelope for Fulencode operations",
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "operation": {
+      "type": "string"
+    },
+    "input_format": {
+      "type": "string"
+    },
+    "output_format": {
+      "type": "string"
+    },
+    "details": {
+      "type": "object",
+      "properties": {
+        "byte_offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "codepoint_offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "detected_encoding": {
+          "type": "string"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "invalid_bytes": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 255
+          }
+        },
+        "expected": {
+          "type": "string"
+        },
+        "actual": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "code",
+    "message",
+    "operation"
+  ],
+  "additionalProperties": false
+}

package/schemas/crucible-ts/library/fulencode/v1.0.0/normalization-result.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/library/fulencode/v1.0.0/normalization-result.schema.json",
+  "title": "Fulencode Normalization Result",
+  "description": "Result payload for fulencode normalize()",
+  "type": "object",
+  "properties": {
+    "text": {
+      "type": "string"
+    },
+    "profile": {
+      "type": "string"
+    },
+    "input_length": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_length": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "transformations_applied": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "semantic_changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "position": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "original": {
+            "type": "string"
+          },
+          "normalized": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "position",
+          "original",
+          "normalized",
+          "reason"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "text",
+    "profile",
+    "input_length",
+    "output_length",
+    "transformations_applied",
+    "semantic_changes",
+    "warnings"
+  ],
+  "additionalProperties": false
+}