cleaker 3.2.0

Who am I, here.

cleaker binds a sovereign .me identity to a namespace surface. It is the resolver — it answers "where does this identity live in the network?"

import me from 'this.me'
import cleaker from 'cleaker'

me('suign', 'secret')                  // sovereign identity — offline, deterministic
const node = cleaker(me)               // → cleaker.me (default public surface)
const node = cleaker(me, 'neurons.me') // → neurons.me
const node = cleaker(me, 'sui-desk')   // → http://sui-desk.local:8161 (LAN)

The two primitives

| | | |---|---| | me('suign', 'secret') | sovereign identity — works offline, no network, no server | | cleaker(me, space) | first public act — projects that identity into a namespace surface |

.me is the kernel — a sovereign computation that works without any external service.
cleaker is the resolver — the surface where an identity becomes addressable.

Space resolution rules

cleaker(me, space) accepts any host form and normalizes it automatically:

| Input | Transport origin | Namespace constant | |---|---|---| | cleaker(me) | https://cleaker.me | cleaker.me | | cleaker(me, 'neurons.me') | https://neurons.me | neurons.me | | cleaker(me, 'sui-desk') | http://sui-desk.local:8161 | sui-desk.local | | cleaker(me, 'sui-desk:9000') | http://sui-desk.local:9000 | sui-desk.local | | cleaker(me, '192.168.1.5') | http://192.168.1.5:8161 | 192.168.1.5 | | cleaker(me, 'sui-laptop.local:8181') | http://sui-laptop.local:8181 | sui-laptop.local |

Rule: bare hostname (no dot) → .local + port 8161. Public domain → https. IP → http + port 8161. Port is transport only — never part of the namespace constant.

Namespace structure

cleaker.me                rootspace — public, verifiable via DNS
suign.cleaker.me          compound  — user prefix + rootspace constant
sui-macbook.local         private/LAN surface
suign.sui-macbook.local   compound on LAN

Same seed, different contextual branches:

me('suign', 'secret')
  ├── cleaker(me, 'neurons.me')  → suign.neurons.me
  ├── cleaker(me, 'sui-desk')    → suign.sui-desk.local
  └── cleaker(me, '192.168.1.5') → suign.192.168.1.5

Change the space, change the branch. Change the seed, change the universe.

Core API

import me from 'this.me'
import cleaker from 'cleaker'

me('suign', 'my-secret')                        // Step 1 — sovereign identity
const node = cleaker(me, 'cleaker.me')           // Step 2 — bind to surface

// Probe all surfaces, open triad, hydrate memories into kernel
const status = await node.validateHosts({
  namespace: 'suign.cleaker.me',
  secret: 'my-secret',
})

console.log(status.overall)                      // 'healthy' | 'degraded' | 'offline'
console.log(status.hosts[0].status.triad)        // 'verified' | 'unverified' | 'failed' | 'skipped'

// Wait until a surface is verified and memories are hydrated
await node.waitUntilReady()

// Explicit sign-in
const result = await node.signIn({
  namespace: 'suign.cleaker.me',
  secret: 'my-secret',
})
// result.status === 'verified'
// result.memoriesCount — memories replayed into kernel

// Discover known hosts for the namespace
const hosts = node.discoverHosts()

CleakerOptions

const node = cleaker(me, 'cleaker.me', {
  namespace: 'suign.cleaker.me',       // explicit namespace override
  secret: 'my-secret',                 // auto-signIn at bind time
  fetcher: customFetch,                // inject fetch (tests, custom transport)
  bootstrap: ['http://localhost:8161'], // additional surfaces to probe
})

Surface fallback & observability

When a remote surface fails, cleaker automatically tries the next surface in the priority list and emits structured events so callers can log or react to the degraded path.

const node = cleaker(me, 'cleaker.me')

// Emitted when a remote surface fails and a local surface is next
node.on('namespace:fallback', ({ namespace, failedOrigin, failedReason, fallbackOrigin }) => {
  console.warn(`[${namespace}] ${failedOrigin} failed (${failedReason}) → retrying on ${fallbackOrigin}`)
})

// Emitted when ALL surfaces have been tried and resolution gives up
node.on('namespace:failed', ({ namespace, tried, explain }) => {
  // explain is human-readable:
  // "namespace 'suign.cleaker.me' failed to resolve. tried 3 surfaces:
  //   [1] https://cleaker.me → NETWORK_ERROR
  //   [2] https://suis-macbook-air.local → NETWORK_ERROR
  //   [3] http://localhost:8161 → NETWORK_ERROR"
  console.error(explain)
  tried.forEach(t => console.error(t.origin, t.reason))
})

await node.validateHosts({ namespace: 'suign.cleaker.me', secret: 'my-secret' })

Auto-discovered fallback chain (no config required):

1. Configured surface (space argument)
2. Environment (CLEAKER_NAMESPACE_ROOT / CLEAKER_NAMESPACE_HOST)
3. Machine hostname via os.hostname() → e.g. suis-macbook-air.local
4. http://localhost:8161 (development default)

Every machine discovers its own local surface automatically — the same mechanism that lets monads find and announce themselves on the LAN.

Full events API

// CleakerStatus emitted on every state transition
node.on('status:change', (status: CleakerStatus) => {})

// Fires when the first surface is verified and memories are hydrated
node.on('ready', (payload: CleakerReadyPayload) => {})

// Per-host error during triad open
node.on('error', ({ code, message, hostId }) => {})

// A specific host passed triad verification
node.on('host:triad:success', (hostId: string) => {})

// A remote surface failed; local fallback is next
node.on('namespace:fallback', (payload: NamespaceFallbackPayload) => {})

// All surfaces exhausted; namespace resolution giving up
node.on('namespace:failed', (payload: NamespaceFailedPayload) => {})

Unsubscribe by calling the returned function:

const unsub = node.on('ready', handler)
unsub() // removes the handler

Remote pointer

A semantic address — no kernel, no network call at creation time:

import cleaker from 'cleaker'

const ptr = cleaker('me://ana.cleaker.me:read/profile')
// ptr.__ptr.resolution.status === 'unresolved'
// Resolved lazily on first access or explicit .resolve()

Monad scope-chain routing

Targets use monad[name] syntax for scope-chain routing:

me://suign.cleaker.me:read/monad[frank]/projects/x

Resolves frank via fallback chain:

1. frank @ suign.cleaker.me   (compound — exact match)
2. frank @ cleaker.me         (rootspace — fallback)
3. 404

Same name, different contextual projections. Mirrors JS prototype chain / CSS cascade / DNS fallback.

Install

npm install cleaker

Architecture

this.me    → sovereign kernel. derives identity from (who, secret) seed. works offline.
cleaker    → resolver. projects .me into a namespace surface. emits fallback events.
monad.ai   → daemon. exposes the namespace over HTTP. runs the mesh.

Resolutio ante directionem — nomen ante locum. Resolution before direction. Name before place.

Who are we, here.