permid64 0.1.0__py3-none-any.whl

permid64/__init__.py

@@ -0,0 +1,17 @@
+"""
+permid64 — Clock-free, persistent, obfuscated 64-bit ID generation.
+
+Public API
+----------
+    from permid64 import Id64, DecodedId
+
+    gen = Id64.multiplicative(instance_id=1, state_file="id64.state")
+    uid = gen.next_u64()
+    meta = gen.decode(uid)   # DecodedId(raw=..., instance_id=1, sequence=0)
+"""
+from .generator import Id64
+from .permutation import Permutation64Protocol
+from .types import DecodedId
+
+__all__ = ["Id64", "DecodedId", "Permutation64Protocol"]
+__version__ = "0.1.0"

permid64/generator.py

@@ -0,0 +1,122 @@
+"""
+generator.py — Id64: the main public façade.
+
+Usage
+-----
+    # Multiplicative (fast, simpler)
+    gen = Id64.multiplicative(
+        instance_id=42,
+        state_file="id64.state",
+        block_size=4096,
+        a=0x9E3779B185EBCA87,
+        b=0x6A09E667F3BCC909,
+    )
+
+    # Feistel (better statistical mixing)
+    gen = Id64.feistel(
+        instance_id=42,
+        state_file="id64.state",
+        block_size=4096,
+        key=0xDEADBEEFCAFEBABE,
+        rounds=6,
+    )
+
+    id_val = gen.next_u64()      # -> int  (unsigned 64-bit)
+    meta   = gen.decode(id_val)  # -> DecodedId(raw, instance_id, sequence)
+"""
+from __future__ import annotations
+
+from .layout import Layout64
+from .permutation import Feistel64Permutation, MultiplyOddPermutation, Permutation64Protocol
+from .source import PersistentCounterSource
+from .types import DecodedId
+
+
+class Id64:
+    """
+    Clock-free 64-bit ID generator.
+
+    Architecture
+    ------------
+    seq  = source.next()                    # monotonic counter (persistent)
+    raw  = layout.compose(instance_id, seq) # pack bits
+    id64 = permutation.forward(raw)         # obfuscate
+
+    Decode
+    ------
+    raw  = permutation.inverse(id64)
+    meta = layout.decompose(raw)
+    """
+
+    def __init__(
+        self,
+        instance_id: int,
+        source: PersistentCounterSource,
+        permutation: Permutation64Protocol,
+        layout: Layout64 | None = None,
+    ) -> None:
+        self.instance_id = instance_id
+        self.source = source
+        self.permutation = permutation
+        self.layout = layout or Layout64()
+
+    # ------------------------------------------------------------------
+    # Factory constructors
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def multiplicative(
+        cls,
+        instance_id: int,
+        state_file: str,
+        block_size: int = 4096,
+        a: int = 0x9E3779B185EBCA87,
+        b: int = 0x6A09E667F3BCC909,
+    ) -> "Id64":
+        """
+        Create a generator backed by a multiply-odd (affine) permutation.
+
+        ``a`` defaults to the 64-bit golden-ratio constant; ``b`` adds a
+        second independent mixing constant.  Both can be overridden.
+        """
+        return cls(
+            instance_id=instance_id,
+            source=PersistentCounterSource(state_file, block_size),
+            permutation=MultiplyOddPermutation(a=a, b=b),
+        )
+
+    @classmethod
+    def feistel(
+        cls,
+        instance_id: int,
+        state_file: str,
+        block_size: int = 4096,
+        key: int = 0xDEADBEEFCAFEBABE,
+        rounds: int = 6,
+    ) -> "Id64":
+        """
+        Create a generator backed by a 64-bit Feistel-network permutation.
+
+        ``key`` is a 64-bit seed from which round keys are derived.
+        ``rounds`` defaults to 6 (good mixing / speed balance).
+        """
+        return cls(
+            instance_id=instance_id,
+            source=PersistentCounterSource(state_file, block_size),
+            permutation=Feistel64Permutation(key=key, rounds=rounds),
+        )
+
+    # ------------------------------------------------------------------
+    # Core API
+    # ------------------------------------------------------------------
+
+    def next_u64(self) -> int:
+        """Return the next unique, obfuscated 64-bit ID."""
+        seq = self.source.next()
+        raw = self.layout.compose(self.instance_id, seq)
+        return self.permutation.forward(raw)
+
+    def decode(self, id64: int) -> DecodedId:
+        """Reverse a previously generated ID back to its metadata."""
+        raw = self.permutation.inverse(id64)
+        return self.layout.decompose(raw)

permid64/layout.py

@@ -0,0 +1,54 @@
+"""
+layout.py — Pack / unpack instance_id + sequence into a single 64-bit integer.
+
+Default split: 16 bits for instance_id  (up to 65 535 shards)
+               48 bits for sequence      (up to 281 trillion IDs per shard)
+"""
+from .types import DecodedId
+
+MASK64 = 0xFFFFFFFFFFFFFFFF
+
+
+class Layout64:
+    """
+    Bit-layout for the 64-bit raw value.
+
+    instance_id occupies the top `instance_bits` bits.
+    sequence    occupies the bottom `sequence_bits` bits.
+    """
+
+    def __init__(self, instance_bits: int = 16, sequence_bits: int = 48) -> None:
+        if instance_bits + sequence_bits != 64:
+            raise ValueError(
+                f"instance_bits ({instance_bits}) + sequence_bits ({sequence_bits}) must equal 64"
+            )
+        self.instance_bits = instance_bits
+        self.sequence_bits = sequence_bits
+        self.sequence_mask = (1 << sequence_bits) - 1
+        self.instance_mask = (1 << instance_bits) - 1
+
+    def compose(self, instance_id: int, sequence: int) -> int:
+        """
+        Pack instance_id and sequence into a single 64-bit integer.
+
+        Both values are silently masked to their configured bit widths.
+        Values exceeding the field width (e.g. instance_id >= 2^instance_bits)
+        will have their high bits truncated without raising an error.
+        Use ``instance_mask`` / ``sequence_mask`` to validate inputs if
+        strict overflow detection is required.
+        """
+        if sequence > self.sequence_mask:
+            raise OverflowError(
+                f"sequence {sequence} exceeds {self.sequence_bits}-bit maximum "
+                f"({self.sequence_mask}). The ID space for this shard is exhausted."
+            )
+        return (
+            ((instance_id & self.instance_mask) << self.sequence_bits)
+            | (sequence & self.sequence_mask)
+        ) & MASK64
+
+    def decompose(self, raw: int) -> DecodedId:
+        """Unpack a raw 64-bit integer back into instance_id and sequence."""
+        seq = raw & self.sequence_mask
+        instance_id = (raw >> self.sequence_bits) & self.instance_mask
+        return DecodedId(raw=raw, instance_id=instance_id, sequence=seq)

permid64/permutation.py

@@ -0,0 +1,175 @@
+"""
+permutation.py — Invertible 64-bit permutations for permid64.
+
+Protocol
+--------
+Permutation64Protocol
+    Structural protocol for any invertible 64-bit permutation.
+    Implement ``forward`` and ``inverse`` to plug in a custom permutation.
+
+Two built-in implementations:
+
+MultiplyOddPermutation
+    f(x) = (a·x + b) mod 2^64
+    Requires a to be odd (guarantees the modular inverse exists).
+    Extremely fast; statistical mixing is adequate for opaque IDs.
+
+Feistel64Permutation
+    A balanced 64-bit Feistel network (left/right each 32 bits).
+    The network is inherently invertible regardless of the round function.
+    Round keys are derived from a single 64-bit seed via a simple KDF.
+    Default: 6 rounds (good mixing / speed trade-off).
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+MASK64 = 0xFFFFFFFFFFFFFFFF
+MASK32 = 0xFFFFFFFF
+
+
+@runtime_checkable
+class Permutation64Protocol(Protocol):
+    """
+    Structural protocol for invertible 64-bit permutations.
+
+    Any class that implements ``forward`` and ``inverse`` satisfies this
+    protocol and can be passed to ``Id64.__init__`` as a permutation.
+    This enables dependency injection of custom permutations (e.g. an
+    AES-based Format-Preserving Encryption scheme) without modifying
+    the library.
+
+    Contract:
+        - Both ``forward`` and ``inverse`` operate over [0, 2^64).
+        - ``inverse(forward(x)) == x`` for all x in [0, 2^64).
+        - ``forward(inverse(y)) == y`` for all y in [0, 2^64).
+    """
+
+    def forward(self, x: int) -> int:
+        """Map x -> y, where both are unsigned 64-bit integers."""
+        ...
+
+    def inverse(self, y: int) -> int:
+        """Map y -> x, exactly reversing forward()."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Multiply-odd (affine) permutation
+# ---------------------------------------------------------------------------
+
+class MultiplyOddPermutation:
+    """
+    f(x) = (a·x + b) mod 2^64
+
+    ``a`` must be odd so that the modular inverse exists.
+    ``b`` can be any 64-bit integer (acts as an additive offset / "salt").
+    """
+
+    def __init__(self, a: int, b: int) -> None:
+        a = a & MASK64
+        if a % 2 == 0:
+            raise ValueError(
+                f"'a' must be odd for the permutation to be invertible mod 2^64, got {a:#x}"
+            )
+        self.a: int = a
+        self.b: int = b & MASK64
+        # Compute modular inverse of a mod 2^64 via extended Euclidean algorithm.
+        self.a_inv: int = pow(a, -1, 1 << 64)
+
+    def forward(self, x: int) -> int:
+        return (x * self.a + self.b) & MASK64
+
+    def inverse(self, y: int) -> int:
+        return ((y - self.b) * self.a_inv) & MASK64
+
+
+# ---------------------------------------------------------------------------
+# Feistel-64 permutation
+# ---------------------------------------------------------------------------
+
+class Feistel64Permutation:
+    """
+    A balanced Feistel network over 64-bit integers.
+
+    The 64-bit block is split into two 32-bit halves (L, R).
+    Each round:
+        L', R' = R, L XOR F(R, round_key)
+
+    Because F need not be invertible, the whole network is still
+    a permutation — the inverse simply applies rounds in reverse
+    order swapping the roles of L and R.
+
+    Round keys are derived from ``key`` using a simple xorshift-multiply KDF.
+    """
+
+    def __init__(self, key: int, rounds: int = 6) -> None:
+        if rounds < 1:
+            raise ValueError("rounds must be >= 1")
+        self.rounds = rounds
+        self.round_keys = self._derive_round_keys(key & MASK64, rounds)
+
+    # ------------------------------------------------------------------
+    # Key derivation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _derive_round_keys(key: int, rounds: int) -> list[int]:
+        """Derive ``rounds`` independent 32-bit sub-keys from a 64-bit seed."""
+        keys: list[int] = []
+        x = key & MASK64
+        for _ in range(rounds):
+            # xorshift64* step
+            x ^= (x >> 12) & MASK64
+            x ^= (x << 25) & MASK64
+            x ^= (x >> 27) & MASK64
+            x = (x * 0x2545F4914F6CDD1D) & MASK64
+            keys.append(x & MASK32)
+        return keys
+
+    # ------------------------------------------------------------------
+    # Round function  F: (32-bit half, 32-bit key) -> 32-bit output
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _round_f(r: int, k: int) -> int:
+        """
+        32-bit mixing function F(r, k) used in each Feistel round.
+
+        Constants used:
+          0x9E3779B1 — Knuth multiplicative hash constant (32-bit version of
+                       the golden-ratio multiplier 2654435761).  Chosen for
+                       near-uniform bit avalanche when used as a multiplier.
+          0x85EBCA6B — MurmurHash3 finalisation constant.  Provides a second
+                       independent mixing stage with strong avalanche.
+
+        The pipeline is: XOR with round-key -> Knuth multiply -> XOR-shift ->
+        left-rotate 5 -> MurmurHash3 multiply -> XOR-shift.  This gives
+        adequate bit diffusion for an obfuscation permutation while remaining
+        fast enough for high-throughput ID generation.
+        """
+        x = (r ^ k) & MASK32
+        x = (x * 0x9E3779B1) & MASK32
+        x ^= (x >> 16)
+        x = ((x << 5) | (x >> 27)) & MASK32   # left-rotate 5
+        x = (x * 0x85EBCA6B) & MASK32
+        x ^= (x >> 13)
+        return x & MASK32
+
+    # ------------------------------------------------------------------
+    # Forward / inverse
+    # ------------------------------------------------------------------
+
+    def forward(self, x: int) -> int:
+        lo = (x >> 32) & MASK32
+        r = x & MASK32
+        for k in self.round_keys:
+            lo, r = r, (lo ^ self._round_f(r, k)) & MASK32
+        return ((lo << 32) | r) & MASK64
+
+    def inverse(self, y: int) -> int:
+        lo = (y >> 32) & MASK32
+        r = y & MASK32
+        for k in reversed(self.round_keys):
+            lo, r = (r ^ self._round_f(lo, k)) & MASK32, lo
+        return ((lo << 32) | r) & MASK64

permid64/source.py

@@ -0,0 +1,105 @@
+"""
+source.py — Counter sources for id64.
+
+PersistentCounterSource
+  - Reads / writes a plain-text state file to survive restarts.
+  - Uses block reservation to minimise fsync overhead.
+  - Guarantees: no duplicates across restarts; gaps are allowed after a crash.
+  - Thread-safe via a threading.Lock.
+"""
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+try:
+    import fcntl as _fcntl
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False  # Windows: flock not available
+
+
+class PersistentCounterSource:
+    """
+    A monotonically increasing counter backed by a file.
+
+    On startup it reads ``state_file`` to find the last reserved high-water
+    mark, then immediately reserves the next block of ``block_size`` values
+    and writes the new high-water mark back to disk.  Subsequent calls to
+    ``next()`` are served from memory until the block is exhausted, at which
+    point a new block is reserved.
+
+    If the process crashes mid-block the unused sequence numbers in that
+    block are lost (gaps), but sequence numbers already issued are never
+    reused.
+    """
+
+    def __init__(self, state_file: str, block_size: int = 4096) -> None:
+        if block_size < 1:
+            raise ValueError("block_size must be >= 1")
+        self.path = Path(state_file)
+        self.block_size = block_size
+        self._lock = threading.Lock()
+        self._next: int = 0
+        self._limit: int = 0  # _next < _limit while block is live
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _read_highwater(self) -> int:
+        """Return the persisted high-water mark (0 if file absent/empty)."""
+        if not self.path.exists():
+            return 0
+        text = self.path.read_text().strip()
+        return int(text) if text else 0
+
+    def _write_highwater(self, value: int) -> None:
+        """Atomically write the new high-water mark."""
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(str(value))
+        tmp.replace(self.path)  # atomic rename on POSIX
+
+    def _reserve_block(self) -> None:
+        """
+        Reserve the next block; must be called under self._lock.
+
+        Uses ``fcntl.flock`` (POSIX only) as a best-effort advisory lock
+        during the read-modify-write cycle.  This reduces — but does not
+        fully eliminate — the risk of two processes accidentally sharing the
+        same state file.  For guaranteed multi-process safety, assign each
+        process a distinct state file and instance_id.
+        """
+        lock_fd = None
+        try:
+            if _HAS_FLOCK:
+                lock_fd = open(self.path, "a")  # open/create for locking
+                _fcntl.flock(lock_fd, _fcntl.LOCK_EX)
+            highwater = self._read_highwater()
+            new_highwater = highwater + self.block_size
+            self._write_highwater(new_highwater)
+            self._next = highwater
+            self._limit = new_highwater
+        finally:
+            if lock_fd is not None:
+                _fcntl.flock(lock_fd, _fcntl.LOCK_UN)
+                lock_fd.close()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def next(self) -> int:
+        """Return the next unique sequence number."""
+        with self._lock:
+            if self._next >= self._limit:
+                self._reserve_block()
+            val = self._next
+            self._next += 1
+            return val
+
+    @property
+    def current_highwater(self) -> int:
+        """Return the persisted high-water mark (for inspection / testing)."""
+        return self._read_highwater()

permid64/types.py

@@ -0,0 +1,12 @@
+"""
+types.py — Shared dataclasses for id64.
+"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DecodedId:
+    """Result of Id64.decode()."""
+    raw: int          # the raw 64-bit value before permutation
+    instance_id: int  # the machine / process shard identifier
+    sequence: int     # monotonically increasing counter value

permid64-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: permid64
+Version: 0.1.0
+Summary: Clock-free, persistent, reversible-permutation 64-bit ID generation
+License: MIT
+Project-URL: Repository, https://github.com/erickh826/permid64
+Project-URL: Issues, https://github.com/erickh826/permid64/issues
+Keywords: id,uuid,unique-id,feistel,permutation,counter,clock-free
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# permid64
+
+**Clock-free, persistent, reversible-permutation 64-bit ID generation.**
+
+> *Counter in, permutation out.*
+
+permid64 generates unique 64-bit integer IDs without relying on wall-clock time. It combines a crash-safe persistent counter with an invertible permutation to produce IDs that look random but carry recoverable metadata.
+
+```
+# Raw counter (leaks business volume at a glance)
+1001, 1002, 1003 ...
+
+# permid64 (shuffled surface, recoverable structure)
+12609531668580943872, 7349201938475629, 3847291038012847 ...
+# decode(12609531668580943872)  →  instance_id=42, sequence=0
+```
+
+---
+
+## What it is
+
+- A **clock-free** 64-bit ID generator — no timestamp, no NTP dependency
+- IDs are **unique** because the source is a monotonically increasing counter
+- IDs **look shuffled** because they pass through a reversible permutation
+- The permutation is **invertible** — `decode()` recovers the original metadata
+
+## What it is not
+
+- **Not a timestamp-based scheme** — there is no time component in the ID
+- **Not a UUID replacement for every scenario** — if you need a globally unique random token with no infrastructure at all, UUID v4 is simpler
+- **Not cryptographic encryption** — the permutation is an obfuscation layer, not authenticated encryption; do not use IDs as secrets or security tokens
+- **Not safe for multiple processes sharing one state file** — `PersistentCounterSource` is single-process only; concurrent writes from multiple processes to the same state file will cause duplicates (see [Limitations](#limitations))
+
+---
+
+## Design
+
+```
+seq  = source.next()                    # monotonic counter (persistent)
+raw  = layout.compose(instance_id, seq) # pack 16-bit shard + 48-bit seq
+id64 = permutation.forward(raw)         # obfuscate with invertible bijection
+```
+
+**Layout** — default 64-bit split:
+
+```
+[ instance_id : 16 bits ][ sequence : 48 bits ]
+```
+
+- Up to **65 535** independent shards
+- Up to **281 trillion** IDs per shard
+
+**Permutations** — both are bijections over `[0, 2^64)`:
+
+| Mode | Formula | Speed | Mixing |
+|---|---|---|---|
+| `multiplicative` | `f(x) = (a·x + b) mod 2^64` | ~500 M/s | Good |
+| `feistel` | 64-bit Feistel network | ~150 M/s | Excellent |
+
+**Persistence** — block reservation strategy:
+1. On startup, read high-water mark from state file.
+2. Reserve a block of N sequence numbers, write new high-water mark.
+3. Serve IDs from memory until block exhausted.
+4. If the process crashes, the unused block is lost (gap), but **no duplicate is ever issued**.
+
+---
+
+## Quick start
+
+```python
+from permid64 import Id64
+
+# Multiplicative (fastest)
+gen = Id64.multiplicative(
+    instance_id=42,
+    state_file="permid64.state",
+    block_size=4096,
+)
+
+uid = gen.next_u64()          # e.g. 12609531668580943872
+meta = gen.decode(uid)
+# DecodedId(raw=2748779069440, instance_id=42, sequence=0)
+print(meta.instance_id, meta.sequence)
+
+# Feistel (better statistical mixing)
+gen2 = Id64.feistel(
+    instance_id=42,
+    state_file="permid64.state",
+    block_size=4096,
+    key=0xDEADBEEFCAFEBABE,
+    rounds=6,
+)
+```
+
+### Why decode() matters
+
+In production, when an anomalous ID appears in a log or alert, you can decode it instantly — no DB lookup needed:
+
+```python
+meta = gen.decode(12609531668580943872)
+print(f"Issued by instance {meta.instance_id}, sequence #{meta.sequence}")
+# Issued by instance 42, sequence #0
+```
+
+This makes incident tracing dramatically faster: you immediately know which shard issued the ID and its approximate position in the issuance history.
+
+### Assigning instance_id
+
+Assign each process or deployment unit a distinct `instance_id`. Common patterns:
+
+```python
+import os
+
+# From environment variable (works in Docker / K8s)
+instance_id = int(os.environ.get("INSTANCE_ID", "0"))
+
+# From K8s StatefulSet pod name (e.g. "worker-3" -> 3)
+import re
+pod_name = os.environ.get("POD_NAME", "worker-0")
+instance_id = int(re.search(r"(\d+)$", pod_name).group(1))
+```
+
+Each `instance_id` gets its own independent sequence space — no coordination needed between shards.
+
+---
+
+## Installation
+
+```bash
+pip install permid64          # once published to PyPI
+# or from source:
+pip install -e ".[dev]"
+```
+
+---
+
+## Running tests
+
+```bash
+pytest
+```
+
+Five acceptance criteria are checked:
+
+1. **Uniqueness** — 1 million IDs, zero duplicates
+2. **Invertibility** — `decode(next_u64())` recovers `instance_id` and `sequence`
+3. **Restart safety** — sequence never resets across process restarts
+4. **Gap tolerance** — crash causes a gap, never a duplicate
+5. **Thread safety** — concurrent generation remains unique
+
+---
+
+## Benchmark
+
+```bash
+python benchmarks/bench_id64.py
+```
+
+Sample output (Apple M2):
+
+```
+[Permutation comparison — block_size=4096]
+  multiplicative (default keys)          ~480,000,000 IDs/sec
+  feistel (6 rounds)                     ~140,000,000 IDs/sec
+  feistel (12 rounds)                     ~80,000,000 IDs/sec
+```
+
+---
+
+## Guarantees
+
+| Guarantee | Notes |
+|---|---|
+| No duplicate IDs within a shard | Strict |
+| No duplicates across restarts | Strict — state file must be on durable storage |
+| Decodable | Only with the same permutation key / params |
+| Gaps allowed | After a crash, some sequence numbers are skipped |
+| No global coordination | Each `instance_id` is fully independent |
+
+---
+
+## Limitations
+
+### Single-process only
+
+`PersistentCounterSource` is **not safe for concurrent use across multiple processes** sharing the same state file. A best-effort `fcntl.flock` advisory lock is applied during block reservation on POSIX systems, but this is not a hard guarantee — do not rely on it as a substitute for proper shard isolation.
+
+The correct pattern for multiple processes is to assign each a **distinct `instance_id`** and a **distinct state file**. Multi-process coordination via a central allocator is planned for v0.3.
+
+### Feistel is obfuscation, not encryption
+
+The Feistel permutation provides strong mixing and is reversible, but it is not a formally audited cryptographic primitive. Do not rely on it for access control, token authentication, or any security-sensitive use case.
+
+### instance_id must be assigned manually
+
+There is no automatic shard coordination. Assign `instance_id` values via config or environment variables and ensure they are unique across your deployment.
+
+### Sequence space is large but finite
+
+The default 48-bit sequence space supports ~281 trillion IDs per shard. This is enough for virtually all workloads, but it is not infinite.
+
+---
+
+## Architecture
+
+```
+permid64/
+  __init__.py       # public exports: Id64, DecodedId
+  generator.py      # Id64 façade
+  source.py         # PersistentCounterSource
+  layout.py         # Layout64 — pack/unpack 64-bit raw value
+  permutation.py    # MultiplyOddPermutation, Feistel64Permutation
+  types.py          # DecodedId dataclass
+
+tests/
+  test_counter.py
+  test_layout.py
+  test_permutation.py
+  test_id64_e2e.py   # the 5 MVP acceptance tests
+
+benchmarks/
+  bench_id64.py
+```
+
+---
+
+## Roadmap
+
+| Version | Focus |
+|---|---|
+| v0.1 (current) | Core: counter + permutation + decode |
+| v0.2 | `IdentityPermutation`, Base32/Base62 encoding, `Id64Config` |
+| v0.3 | Multi-process file locking, `ReservedBlockSource` (central allocator) |
+| v0.4+ | Rust/Go reference implementations, formal cross-language spec |
+
+---
+
+## License
+
+MIT

permid64-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+permid64/__init__.py,sha256=lXErKnIkyRCYm2O4ZnboZ0HWcyCc8mreNVNlorM_5wU,499
+permid64/generator.py,sha256=vnv8uC3tY8o7vrwyYkw7kucnb8X52i5P2rfY3Bcl4u4,3670
+permid64/layout.py,sha256=iMu_mauWm2yylVJ6YF-zQmtlObrFrTIwP94CWgx2AeY,2158
+permid64/permutation.py,sha256=dFKa1tXqzQbCuz-oDPEk2wxphA5Q5gBxGz4DtQM7Ehs,6243
+permid64/source.py,sha256=JrCGGHlUZHbAJsEz5m8J5jebyA13AW4Ulxt59bfuNHk,3863
+permid64/types.py,sha256=ZlXj8Wwz0Z1PnDeJkAEwOoAnzSlwwkLFvjQ_HMg7oyc,352
+permid64-0.1.0.dist-info/METADATA,sha256=N_z35_N2Hl74lJZKTry9Bw8JnFTkv6DpoGtXCOvdujk,8502
+permid64-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+permid64-0.1.0.dist-info/top_level.txt,sha256=9UnJlIvP_Qxgvd1cAJzKYGnL5VVn5znPi6l5EDLuupQ,9
+permid64-0.1.0.dist-info/RECORD,,

permid64-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

permid64-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+permid64