baseh 1.1.0 → 2.0.2

data/lib/baseh.rb

@@ -10,54 +10,132 @@ require_relative "baseh/checksum"
 require_relative "baseh/feistel"
 require_relative "baseh/profiles"
 require_relative "baseh/baseh"
-require_relative "baseh/zero"
 
 # baseH (Human Reference Code) codec. See spec/IMPLEMENTATION_CODEC.md in the
 # repository root for the normative specification.
 module Baseh
+  # The frozen published permutation key used by every plain tier helper.
+  # Public by design: it makes issued codes look non-sequential but offers no
+  # secrecy, since anyone can read it here. Never swap it on a live
+  # namespace; codes only decode with the key they were issued under. Use
+  # the -p helpers to supply private key material.
+  FROZEN_KEY_BYTES = Profiles::FROZEN_KEY_BYTES
+
   class << self
     # Frozen tier baseh-minimum-v1: alphanumeric with no strips, no checksum,
-    # hyphen-delimited XXX-XXX. Permutation off.
+    # hyphen-delimited XXX-XXX. Permutes with the frozen published key.
     def baseh_minimum_v1
       Profiles.baseh_minimum_v1
     end
 
-    # baseh-minimum with feistel-v1 permutation. key_bytes is required.
+    # baseh-minimum permuted with caller-supplied key material. key_bytes is required.
     def baseh_minimum_p_v1(key_bytes:, key_id: "default", rounds: 8)
       Profiles.baseh_minimum_p_v1(key_bytes: key_bytes, key_id: key_id, rounds: rounds)
     end
 
-    # Frozen tier baseh-light-v1: visual light plus spoken light, one
-    # checksum symbol. Permutation off.
+    # Frozen tier baseh-light-v1: visual light plus spoken light, two
+    # checksum symbols, hyphen-delimited. Permutes with the frozen published
+    # key.
     def baseh_light_v1
       Profiles.baseh_light_v1
     end
 
-    # baseh-light with feistel-v1 permutation. key_bytes is required.
+    # baseh-light permuted with caller-supplied key material. key_bytes is required.
     def baseh_light_p_v1(key_bytes:, key_id: "default", rounds: 8)
       Profiles.baseh_light_p_v1(key_bytes: key_bytes, key_id: key_id, rounds: rounds)
     end
 
-    # Frozen tier baseh-medium-v1: visual medium plus spoken medium, one
-    # checksum symbol. The default. Permutation off.
+    # Frozen tier baseh-medium-v1: visual medium plus spoken medium, two
+    # checksum symbols, hyphen-delimited. The default. Permutes with the
+    # frozen published key.
     def baseh_medium_v1
       Profiles.baseh_medium_v1
     end
 
-    # baseh-medium with feistel-v1 permutation. key_bytes is required.
+    # baseh-medium permuted with caller-supplied key material. key_bytes is required.
     def baseh_medium_p_v1(key_bytes:, key_id: "default", rounds: 8)
       Profiles.baseh_medium_p_v1(key_bytes: key_bytes, key_id: key_id, rounds: rounds)
     end
 
     # Frozen tier baseh-heavy-v1: conservative alphabet plus spoken heavy,
-    # one checksum symbol. Permutation off.
+    # two checksum symbols, hyphen-delimited. Permutes with the frozen
+    # published key.
     def baseh_heavy_v1
       Profiles.baseh_heavy_v1
     end
 
-    # baseh-heavy with feistel-v1 permutation. key_bytes is required.
+    # baseh-heavy permuted with caller-supplied key material. key_bytes is required.
     def baseh_heavy_p_v1(key_bytes:, key_id: "default", rounds: 8)
       Profiles.baseh_heavy_p_v1(key_bytes: key_bytes, key_id: key_id, rounds: rounds)
     end
+
+    # Frozen tier baseh-expandable-v1: variable-length codes, four characters
+    # while the namespace is small and growing one symbol per generation.
+    # Permutes per generation with the frozen published key.
+    def baseh_expandable_v1
+      Profiles.baseh_expandable_v1
+    end
+
+    # baseh-expandable permuted with caller-supplied key material. key_bytes is required.
+    def baseh_expandable_p_v1(key_bytes:, key_id: "default", rounds: 8)
+      Profiles.baseh_expandable_p_v1(key_bytes: key_bytes, key_id: key_id, rounds: rounds)
+    end
+
+    # Zero-config facade over the frozen baseh-expandable-v1 profile, the
+    # recommended default for new namespaces. Most applications never need a
+    # profile object at all: these methods share one lazily constructed,
+    # stateless codec instance (thread-safe once built, per Baseh::Baseh).
+    #
+    #   Baseh.encode(123456)        -> String canonical code
+    #   Baseh.decode(code).id       -> 123456
+    #   Baseh.validate(code).valid  -> true/false
+    #
+    # decode returns the full DecodeResult (id, canonical_code, corrected)
+    # and validate returns the full ValidateResult (valid, canonical_code,
+    # reason), exactly as the instance API does.
+
+    # Encode an identifier with the default expandable profile.
+    #
+    # @param id [Integer] any non-negative id
+    # @return [String] canonical code
+    # @raise [BasehError] OUT_OF_RANGE, BLOCKED_CODE
+    def encode(id)
+      default.encode(id: id)
+    end
+
+    # Decode a code from the default expandable profile.
+    #
+    # @param input [String]
+    # @param options keyword options of Baseh::Baseh#decode (accept_spaces:,
+    #   try_correction:, confusion_profile:, max_corrections:)
+    # @return [Baseh::Baseh::DecodeResult]
+    # @raise [BasehError] same codes as the instance decode
+    def decode(input, **options)
+      default.decode(input, **options)
+    end
+
+    # Live as-you-type inspection of input against the default expandable
+    # profile (spec 12.5). Never raises on user input.
+    #
+    # @param input [String]
+    # @return [Baseh::Baseh::InspectResult]
+    def inspect(input)
+      default.inspect(input)
+    end
+
+    # Validate a code against the default expandable profile without raising.
+    #
+    # @param input [String]
+    # @param options keyword options of Baseh::Baseh#validate (the same
+    #   keyword options decode accepts)
+    # @return [Baseh::Baseh::ValidateResult]
+    def validate(input, **options)
+      default.validate(input, **options)
+    end
+
+    # The shared default-profile codec, built on first use.
+    def default
+      @default ||= Baseh.new(Profiles.baseh_expandable_v1)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: baseh
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.2
 platform: ruby
 authors:
 - cloudyventures
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -28,6 +28,7 @@ description: 'Encodes and decodes human reference codes per the baseH codec spec
   fixed-length base-N bodies, rolling polynomial checksums, optional feistel-v1 permutation,
   spoken-confusion correction and profanity safety.'
 email:
+- mat@cloudyventures.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -43,12 +44,13 @@ files:
 - lib/baseh/profile.rb
 - lib/baseh/profiles.rb
 - lib/baseh/version.rb
-- lib/baseh/zero.rb
-homepage:
+homepage: https://github.com/cloudyventures/baseh
 licenses:
 - AGPL-3.0
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/cloudyventures/baseh
+  bug_tracker_uri: https://github.com/cloudyventures/baseh/issues
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/baseh/zero.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module Baseh
-  # Zero-config pair over the frozen baseh-medium-v1 profile. No profile
-  # object, no key: just the two functions an application needs when it
-  # does not want to think about configuration.
-  #
-  #   Baseh.to_code(481890303)     -> "ZZZZZZV"
-  #   Baseh.from_code("ZZZZZZV")   -> 481890303
-  #
-  # to_code accepts an Integer or a decimal string of digits. from_code
-  # strips every whitespace character (edges and internal), accepts
-  # lowercase and the typed aliases (O, I, L) and returns the id as an
-  # Integer. Any invalid input raises BasehError, including the rare
-  # BLOCKED_CODE identifiers that spell a blocklisted word; no correction
-  # attempts are ever made.
-  module Zero
-    DECIMAL = /\A[0-9]+\z/.freeze
-    WHITESPACE = /\s+/.freeze
-
-    ZERO = Baseh.new(Profiles.baseh_medium_v1)
-
-    module_function
-
-    # Encode an identifier with the zero-config Medium profile.
-    #
-    # @param id [Integer, String] Integer or decimal string of digits
-    # @return [String] canonical code
-    # @raise [ArgumentError] when id is neither an Integer nor a decimal string
-    # @raise [BasehError] OUT_OF_RANGE, BLOCKED_CODE
-    def to_code(id)
-      value =
-        case id
-        when Integer then id
-        when String
-          if DECIMAL.match?(id)
-            id.to_i
-          else
-            raise ArgumentError,
-                  "to_code expects a non-negative Integer or a decimal string"
-          end
-        else
-          raise ArgumentError,
-                "to_code expects a non-negative Integer or a decimal string"
-        end
-      ZERO.encode(id: value)
-    end
-
-    # Decode a code from the zero-config Medium profile back to its id.
-    #
-    # @param code [String]
-    # @return [Integer]
-    # @raise [BasehError] INVALID_LENGTH, INVALID_CHARACTER, INVALID_CHECKSUM
-    def from_code(code)
-      input = code.is_a?(String) ? code.gsub(WHITESPACE, "") : code
-      ZERO.decode(input).id
-    end
-  end
-
-  class << self
-    # See Baseh::Zero.to_code.
-    def to_code(id)
-      Zero.to_code(id)
-    end
-
-    # See Baseh::Zero.from_code.
-    def from_code(code)
-      Zero.from_code(code)
-    end
-  end
-end