Signet

draft 1.0.0
  status stable
  title Signet Specification
  date 2026-02-10
  license All Rights Reserved

---

spec signet

  section purpose
    title Purpose
    level 1

    prose
      value
        Signet is a protocol-based data transport harness. It
        provides a single uniform interface (store, retrieve,
        remove, exists) and an immutable registry of per-protocol
        handlers. Application code addresses data by URL; the
        registry routes to the right handler. The same calling
        code works against in-memory state, localStorage, the
        network, or any custom protocol a consumer registers.

  section registry
    title Handler registry
    level 2

    prose
      value
        A registry maps URL protocols (the part before the colon)
        to handler implementations. Registries are immutable;
        registering a handler returns a new registry.

    requirement S-001
      level MUST
      value
        A registry MUST be addressable by URL protocol. Resolving
        an unregistered protocol MUST throw or reject with a
        clearly named error.

    requirement S-002
      level MUST
      value
        Registries MUST be immutable from the outside. The register
        function MUST return a new registry rather than mutating
        its input.

  section operations
    title Operations
    level 3

    prose
      value
        Signet defines four operations over endpoints: store,
        retrieve, remove, and exists. Each accepts one or more
        endpoint URLs; each handler defines how to fulfil the
        operation for its protocol.

    requirement S-010
      level MUST
      value
        Each handler MUST implement $retrieve(url, options) and
        $exists(url, options) at minimum. store and remove are
        implemented by handlers whose backing store is mutable.

    requirement S-011
      level MUST
      value
        Handlers MUST return raw data from $retrieve. The
        operations layer wraps results in { endpoint, data,
        error }.

  section first-party-handlers
    title First-party handlers
    level 4

    prose
      value
        Signet ships ram (in-memory session cache), local
        (localStorage), and https (network) handlers. The same
        registry shape supports any custom protocol a consumer
        cares to add.