@agfpd/iapeer 0.1.0

package/src/codec/index.ts

@@ -0,0 +1,217 @@
+// IAP envelope codec — encoder + decoder, both halves in one module.
+//
+// Encoder: inter-agent-protocol/src/lib/preamble.ts buildEnvelope (wins as-is).
+// Decoder: telegram-runtime/src/cli.ts parseIapEnvelope/extractIapEnvelopes,
+//   rewritten CDATA-AWARE (blueprint-v2 codec-fixes) so that an envelope whose
+//   message contains `</iap>`, `</message>`, `]]>` or a literal CR round-trips
+//   by FIELD-semantic equivalence, not byte-equality.
+//
+// Deliberately NO CR→LF fold here. The old telegram decoder did
+// `xml.replace(/\r\n?/g, '\n')` to repair tmux paste (which rewrites LF→CR).
+// That is a TRANSPORT concern: folding inside the codec silently destroys a
+// literal CR that a caller legitimately put in the message, breaking round-trip.
+// The fold lives in the transport / telegram pane-adapter, not here
+// (blueprint §0.5-ish, brief: "CR→LF fold — в transport/telegram-адаптере, НЕ в codec").
+
+import {
+  IAP_INSTRUCTION,
+  MAX_TOPIC_LEN,
+  normalizeIntelligenceValue,
+  type Intelligence,
+  type Runtime,
+} from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Encoder (canon)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EnvelopeInput {
+  fromPersonality: string
+  fromRuntime: Runtime
+  fromIntelligence: Intelligence
+  topic?: string
+  attachments?: readonly string[]
+  message: string
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function cdata(value: string): string {
+  // A literal `]]>` would terminate the CDATA early. Split it across two
+  // sections; the decoder reconstructs it by concatenating adjacent sections.
+  return `<![CDATA[${value.replaceAll(']]>', ']]]]><![CDATA[>')}]]>`
+}
+
+export function buildEnvelope(input: EnvelopeInput): string {
+  const attrs = [
+    `from-personality="${escapeAttr(input.fromPersonality)}"`,
+    `from-runtime="${escapeAttr(input.fromRuntime)}"`,
+    `from-intelligence="${escapeAttr(input.fromIntelligence)}"`,
+  ]
+  const topic = input.topic?.trim()
+  if (topic) {
+    attrs.push(`topic="${escapeAttr(topic.slice(0, MAX_TOPIC_LEN))}"`)
+  }
+  return [
+    `<iap ${attrs.join(' ')}>`,
+    IAP_INSTRUCTION,
+    ...(input.attachments?.length
+      ? [`<attachments>${cdata(input.attachments.join('\n'))}</attachments>`]
+      : []),
+    `<message>${cdata(input.message)}</message>`,
+    '</iap>',
+  ].join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CDATA-aware low-level scan
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CDATA_OPEN = '<![CDATA['
+const CDATA_CLOSE = ']]>'
+
+/**
+ * Scan from `start` and return the index of the first occurrence of `needle`
+ * that lies OUTSIDE any CDATA section, or -1 if none (or if an unterminated
+ * CDATA section is hit — meaning the buffer is incomplete and the caller should
+ * wait for more input). CDATA sections are skipped wholesale: `]]>` inside them
+ * is the section terminator, never a match for `needle`.
+ */
+function indexOfOutsideCdata(buffer: string, needle: string, start: number): number {
+  let i = start
+  while (i < buffer.length) {
+    if (buffer.startsWith(CDATA_OPEN, i)) {
+      const term = buffer.indexOf(CDATA_CLOSE, i + CDATA_OPEN.length)
+      if (term < 0) return -1 // unterminated CDATA → incomplete buffer
+      i = term + CDATA_CLOSE.length
+      continue
+    }
+    if (buffer.startsWith(needle, i)) return i
+    i++
+  }
+  return -1
+}
+
+/**
+ * Extract and decode the content of `<tag>…</tag>`, treating the body as a
+ * sequence of CDATA sections (and any stray raw text) and concatenating them.
+ * Concatenating adjacent CDATA sections is exactly what reverses the
+ * `]]>` → `]]]]><![CDATA[>` split the encoder performs, so this both
+ * (a) ignores `</tag>` / `</iap>` that appear inside CDATA, and
+ * (b) reconstructs a literal `]]>` in the original payload.
+ * Returns undefined when the open tag is absent or the close tag is never
+ * reached outside CDATA.
+ */
+function readTagContent(xml: string, tag: string): string | undefined {
+  const open = `<${tag}>`
+  const close = `</${tag}>`
+  const openIdx = xml.indexOf(open)
+  if (openIdx < 0) return undefined
+  let i = openIdx + open.length
+  let out = ''
+  while (i < xml.length) {
+    if (xml.startsWith(CDATA_OPEN, i)) {
+      const term = xml.indexOf(CDATA_CLOSE, i + CDATA_OPEN.length)
+      if (term < 0) {
+        // Unterminated CDATA — malformed; treat the remainder as raw content.
+        out += xml.slice(i + CDATA_OPEN.length)
+        return out
+      }
+      out += xml.slice(i + CDATA_OPEN.length, term)
+      i = term + CDATA_CLOSE.length
+      continue
+    }
+    if (xml.startsWith(close, i)) return out
+    out += xml[i]
+    i++
+  }
+  return undefined // close tag never found
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Decoder
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface IapEnvelope {
+  fromPersonality: string
+  fromRuntime: Runtime
+  fromIntelligence?: Intelligence
+  topic?: string
+  attachments: string[]
+  message: string
+}
+
+function attrValue(attrs: string, name: string): string | undefined {
+  const re = new RegExp(`${name}="([^"]*)"`)
+  const m = re.exec(attrs)
+  return m ? unescapeAttr(m[1]) : undefined
+}
+
+function unescapeAttr(value: string): string {
+  // Reverse escapeAttr. Order matters: &amp; LAST so an escaped "&amp;lt;"
+  // in the source does not get double-decoded.
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+export function decodeEnvelope(xml: string): IapEnvelope {
+  const open = /^<iap\s+([^>]*)>/.exec(xml.trim())
+  if (!open) throw new IapError('invalid IAP envelope: missing <iap ...>')
+  const fromPersonality = attrValue(open[1], 'from-personality')
+  const fromRuntime = attrValue(open[1], 'from-runtime')
+  if (!fromPersonality || !fromRuntime) {
+    throw new IapError('invalid IAP envelope: missing from-personality/from-runtime')
+  }
+  // READ-COMPAT: a legacy peer (live telegram) may stamp from-intelligence="human";
+  // normalize human→natural / scripted→absent, drop a genuinely unknown value.
+  const fromIntelligence = normalizeIntelligenceValue(attrValue(open[1], 'from-intelligence'))
+  const message = readTagContent(xml, 'message')
+  if (message === undefined) throw new IapError('invalid IAP envelope: missing message')
+  const attachmentsRaw = readTagContent(xml, 'attachments')
+  const topic = attrValue(open[1], 'topic')
+  return {
+    fromPersonality,
+    fromRuntime,
+    ...(fromIntelligence ? { fromIntelligence } : {}),
+    ...(topic ? { topic } : {}),
+    attachments: attachmentsRaw
+      ? attachmentsRaw.split('\n').map(item => item.trim()).filter(Boolean)
+      : [],
+    message,
+  }
+}
+
+/**
+ * Pull complete `<iap …>…</iap>` envelopes out of a streaming buffer.
+ * The closing `</iap>` is located CDATA-aware, so an envelope whose message
+ * body contains the literal text `</iap>` is not truncated. `rest` holds the
+ * trailing bytes that do not yet form a complete envelope (incl. an envelope
+ * still mid-CDATA), to be prepended to the next chunk.
+ */
+export function extractEnvelopes(buffer: string): { envelopes: string[]; rest: string } {
+  const envelopes: string[] = []
+  let rest = buffer
+  while (true) {
+    const start = rest.indexOf('<iap ')
+    if (start < 0) {
+      // Keep a small tail in case `<iap ` is split across chunk boundaries.
+      return { envelopes, rest: rest.slice(Math.max(0, rest.length - '<iap '.length)) }
+    }
+    if (start > 0) rest = rest.slice(start)
+    const close = indexOfOutsideCdata(rest, '</iap>', '<iap '.length)
+    if (close < 0) return { envelopes, rest } // incomplete (or mid-CDATA) → wait
+    const envelopeEnd = close + '</iap>'.length
+    envelopes.push(rest.slice(0, envelopeEnd))
+    rest = rest.slice(envelopeEnd)
+  }
+}

package/src/core/constants.test.ts

@@ -0,0 +1,21 @@
+// resolveSockDir — the ONE socket-dir resolver every socket-touching site shares
+// (transport scan/resolve, lifecycle, launchdRun). Regression guard against a site
+// re-hardcoding DEFAULT_SOCK_DIR, which made an IAPEER_SOCK_DIR sandbox lie (the
+// session created on the override dir, the resolver scanning /tmp → false offline).
+
+import { describe, expect, test } from 'bun:test'
+import { DEFAULT_SOCK_DIR, resolveSockDir } from './constants.ts'
+
+describe('resolveSockDir', () => {
+  test('no override → DEFAULT_SOCK_DIR (/tmp, contract sock convention)', () => {
+    expect(resolveSockDir({})).toBe(DEFAULT_SOCK_DIR)
+    expect(resolveSockDir({})).toBe('/tmp')
+  })
+  test('IAPEER_SOCK_DIR override is respected (host-wide, like IAPEER_ROOT)', () => {
+    expect(resolveSockDir({ IAPEER_SOCK_DIR: '/tmp/sbx/socks' })).toBe('/tmp/sbx/socks')
+  })
+  test('blank/whitespace override falls back to the default (not an empty dir)', () => {
+    expect(resolveSockDir({ IAPEER_SOCK_DIR: '   ' })).toBe(DEFAULT_SOCK_DIR)
+    expect(resolveSockDir({ IAPEER_SOCK_DIR: '' })).toBe(DEFAULT_SOCK_DIR)
+  })
+})

package/src/core/constants.ts

@@ -0,0 +1,180 @@
+// Canonical constants for the IAPeer foundation.
+// Consolidated from inter-agent-protocol/src/lib/constants.ts (wins as-is) and
+// extended with storage-layer path names (blueprint §1 core/constants).
+
+export const NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
+export const NAME_RE_SOURCE = '^[a-z][a-z0-9-]{0,31}$'
+export const RUNTIME_RE = /^[a-z][a-z0-9]{0,31}$/
+export const RUNTIME_RE_SOURCE = '^[a-z][a-z0-9]{0,31}$'
+
+export type Runtime = string
+export type TmuxRuntime = Runtime
+export const SUPPORTED_LOCAL_RUNTIMES = ['claude', 'codex'] as const
+export type SupportedLocalRuntime = (typeof SUPPORTED_LOCAL_RUNTIMES)[number]
+
+export const PEERS_SCHEMA_VERSION = 2
+export const MAX_DESCRIPTION_LEN = 250
+
+// Contract vocabulary (docs/Идентичность, Артур 05.06): the nature of the
+// intelligence expressing itself through a runtime.
+//   artificial — AI agent · natural — human · absent — programmatic source
+export const INTELLIGENCE_VALUES = ['artificial', 'natural', 'absent'] as const
+export type Intelligence = (typeof INTELLIGENCE_VALUES)[number]
+
+export function isIntelligence(value: unknown): value is Intelligence {
+  return typeof value === 'string' && (INTELLIGENCE_VALUES as readonly string[]).includes(value)
+}
+
+// READ-COMPAT: the live registry/profiles still carry the previous vocabulary
+// (human/scripted) until the coordinated live-fleet migration. The foundation
+// MUST read that data correctly — map legacy → contract on READ only. It does
+// NOT rewrite the live fleet (that migration is a separate, coordinated step;
+// it touches the live telegram human-guard which keys on 'human').
+//   human → natural · scripted → absent
+const LEGACY_INTELLIGENCE: Readonly<Record<string, Intelligence>> = {
+  human: 'natural',
+  scripted: 'absent',
+}
+
+/**
+ * Read-compat normalizer for an intelligence value coming off disk / the wire.
+ * Returns the contract value (passing through artificial/natural/absent and
+ * mapping legacy human→natural / scripted→absent), or undefined when the value
+ * is unrecognised (caller decides whether to throw or fall back to a default).
+ */
+export function normalizeIntelligenceValue(value: unknown): Intelligence | undefined {
+  if (typeof value !== 'string') return undefined
+  if (isIntelligence(value)) return value
+  return LEGACY_INTELLIGENCE[value]
+}
+
+const NATURAL_RUNTIMES = new Set(['telegram', 'discord', 'matrix', 'email', 'web'])
+const ABSENT_RUNTIMES = new Set(['notifier', 'webhook', 'api', 'cron'])
+
+export function defaultIntelligenceForRuntime(runtime: string): Intelligence {
+  if (NATURAL_RUNTIMES.has(runtime)) return 'natural'
+  if (ABSENT_RUNTIMES.has(runtime)) return 'absent'
+  return 'artificial'
+}
+
+// Infra runtimes are ALWAYS-ON (held live by launchd KeepAlive), as opposed to the
+// warm-on-demand agentic runtimes (claude/codex, woken by the daemon). Liveness is
+// a property of the RUNTIME, not the personality (zone Идентичность). Both infra
+// runtimes are routers with a tmux endpoint: telegram receives inbound messages,
+// notifier receives send_to_peer(timer|watcher, …) registration/live-reload — so
+// each needs a live tmux pane for the daemon's deliverViaTmux to paste into. This
+// set gates always-on launchd plist generation (src/launch/launchd.ts).
+const INFRA_RUNTIMES = new Set(['notifier', 'telegram'])
+
+export function isInfraRuntime(runtime: string): boolean {
+  return INFRA_RUNTIMES.has(runtime)
+}
+
+// Each INFRA runtime's always-on plist PINS its launcher binary to an ABSOLUTE
+// path via a runtime-specific env var. launchd gives a job a MINIMAL PATH (no
+// ~/.local/bin, ~/.bun/bin, /opt/homebrew/bin), so a bare `notifier-runtime`
+// would not resolve and the always-on session would crash-loop. The plist baker
+// (launchd.installAlwaysOnPlist) resolves the bin against the rich provisioning
+// PATH and writes the abs path here; launchdRun reads it back into
+// LaunchConfig.{notifierBin,telegramBin} → adapter.buildArgv. SINGLE source for
+// both the baker and the reader so they cannot drift on the var name.
+export const INFRA_RUNTIME_BIN_ENV: Readonly<Record<string, string>> = {
+  notifier: 'NOTIFIER_RUNTIME_BIN',
+  telegram: 'TELEGRAM_RUNTIME_BIN',
+}
+
+/** The PATH-resolvable default launcher name per infra runtime (when no abs path
+ *  is pinned). Mirrors the adapter buildArgv fallbacks (`notifier-runtime` /
+ *  `telegram-runtime`). */
+export const INFRA_RUNTIME_DEFAULT_BIN: Readonly<Record<string, string>> = {
+  notifier: 'notifier-runtime',
+  telegram: 'telegram-runtime',
+}
+
+// codex MCP token-free import (contract Установка §codex MCP). codex REFUSES to import
+// tools from an OPEN streamable-HTTP MCP server — it marks it authStatus=unsupported
+// (and blocks on startup) unless an auth scheme is configured (codex bug #21532). The
+// fix is a NON-SECRET fixed bearer: setting `bearer_token_env_var` flips authStatus to
+// `bearer_token` purely from the config FACT (codex does not require the server to
+// validate the token). The daemon stays OPEN — it ignores `Authorization` and resolves
+// the caller from the X-IAPeer-Identity header (loopback same-uid + per-peer identity
+// is the auth, the same as the claude side). So a codex peer's launch sets this env var
+// to the public stub below; nothing real is gated. Proven live (codex 0.136, gpt-5.5).
+/** The env var codex reads the bearer from (config `bearer_token_env_var`); the launch
+ *  sets it for a codex peer. */
+export const CODEX_BEARER_ENV_VAR = 'IAPEER_BEARER'
+/** The fixed, PUBLIC, non-secret bearer value codex sends to satisfy its own auth gate.
+ *  Deliberately not a secret — the daemon never validates it (it is open on loopback). */
+export const CODEX_DUMMY_BEARER = 'iapeer-localhost-open-no-secret'
+
+export const MAX_MESSAGE_LEN = 16_000
+export const MAX_TOPIC_LEN = 200
+export const MAX_ATTACHMENTS = 20
+export const DEFAULT_SOCK_DIR = '/tmp'
+
+// The directory holding tmux iap-sockets. Canonically /tmp (contract sock convention
+// `/tmp/tmux-iap-<identity>.sock`); IAPEER_SOCK_DIR overrides it host-wide, exactly
+// like IAPEER_ROOT overrides the storage root. EVERY socket-touching site (transport
+// scan/resolve, lifecycle, launchdRun) MUST resolve through this ONE helper so they
+// agree — a site that hardcodes DEFAULT_SOCK_DIR would look in /tmp while a sandbox
+// (IAPEER_SOCK_DIR set) created the session elsewhere → a false "offline".
+export function resolveSockDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.IAPEER_SOCK_DIR?.trim() || DEFAULT_SOCK_DIR
+}
+
+// === per-peer cwd scope ===
+export const IAPEER_DIR = '.iapeer'
+export const PEER_PROFILE_FILE = 'peer-profile.json'
+
+// === global scope ~/.iapeer/ ===
+export const IAP_PLUGIN_DIR = 'iap'
+export const PEERS_PROFILES_FILE = 'peers-profiles.json'
+export const PEERS_PROFILES_LOCK_FILE = 'peers-profiles.lock'
+
+// Storage category roots (blueprint §1 storage). One env override: IAPEER_ROOT.
+export const IAPEER_ROOT_ENV = 'IAPEER_ROOT'
+export const STATE_DIR = 'state'
+export const LOGS_DIR = 'logs'
+export const CACHE_DIR = 'cache'
+export const PLUGINS_DIR = 'plugins'
+export const RUNTIMES_DIR = 'runtimes'
+// The default home for foundation-provisioned peer cwds (`iapeer create` lands a peer
+// here when --path is not given): ~/.iapeer/peers/<personality>. Foundation-owned and
+// collision-free — unlike the organic ~/Peers/ the legacy fleet grew in (NOT the
+// default; existing ~/Peers/* peers are grandfathered, the registry holds any cwd).
+export const PEERS_HOME_DIR = 'peers'
+
+// launchd labels (future lifecycle/daemon phases; named here so storage/cli agree).
+export const LAUNCHD_LABEL_PREFIX = 'com.iapeer.'
+export const DAEMON_PLIST_LABEL = 'com.agfpd.iapeer'
+
+export const IAP_INSTRUCTION =
+  'IAP message from known peers. Reply via send_to_peer.'
+
+export const ALWAYS_LOAD_META = {
+  'anthropic/alwaysLoad': true,
+} as const
+
+export function isRuntime(value: unknown): value is Runtime {
+  return typeof value === 'string' && RUNTIME_RE.test(value)
+}
+
+export function isTmuxRuntime(value: unknown): value is TmuxRuntime {
+  return isRuntime(value)
+}
+
+export function isSupportedLocalRuntime(value: unknown): value is SupportedLocalRuntime {
+  return (
+    typeof value === 'string' &&
+    (SUPPORTED_LOCAL_RUNTIMES as readonly string[]).includes(value)
+  )
+}
+
+export function isValidName(value: unknown): boolean {
+  return typeof value === 'string' && NAME_RE.test(value)
+}
+
+// The name normalizer (normalize(s) = slug(transliterate(s))) lives in its own
+// module so the transliteration engine is swappable behind one interface; it is
+// re-exported here so existing `from '../core/constants.ts'` importers are unchanged.
+export { normalizeNameCandidate } from './normalize.ts'

package/src/core/errors.ts

@@ -0,0 +1,20 @@
+// Result type + IapError. Consolidated from inter-agent-protocol/src/lib/errors.ts (as-is).
+
+export class IapError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'IapError'
+  }
+}
+
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: IapError }
+
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value }
+}
+
+export function err<T = never>(message: string): Result<T> {
+  return { ok: false, error: new IapError(message) }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './constants.ts'
+export * from './errors.ts'
+export * from './socket.ts'

package/src/core/normalize.test.ts

@@ -0,0 +1,98 @@
+// normalizeNameCandidate — the shared name normalizer (normalize = slug∘translit).
+// Covers the zone goldens, ASCII non-regression, writing systems (Cyrillic / Greek
+// / CJK), idempotency, the ICU `№` symbol-alignment, and the fail-to-explicit edge
+// (a non-transliterable / leading-digit / empty result is returned AS-IS and does
+// NOT satisfy NAME_RE, so the caller can reject it rather than invent a name).
+
+import { describe, expect, test } from 'bun:test'
+import { isValidName, NAME_RE, normalizeNameCandidate as normalize } from './constants.ts'
+
+describe('normalizeNameCandidate — zone goldens', () => {
+  test.each([
+    ['Café №2', 'cafe-no-2'], // accents + ICU `№ → No.` symbol alignment
+    ['项目', 'xiang-mu'], // Han → pinyin WITH syllable spacing
+    ['My Project', 'my-project'],
+  ])('%j → %j', (input, expected) => {
+    expect(normalize(input)).toBe(expected)
+  })
+})
+
+describe('normalizeNameCandidate — ASCII non-regression', () => {
+  test.each([
+    ['iapeer', 'iapeer'],
+    ['boris', 'boris'],
+    ['notifier-timer', 'notifier-timer'], // hyphen preserved, not collapsed
+    ['darwin', 'darwin'],
+  ])('%j → %j', (input, expected) => {
+    expect(normalize(input)).toBe(expected)
+  })
+})
+
+describe('normalizeNameCandidate — writing systems (ICU Any-Latin; Latin-ASCII)', () => {
+  test.each([
+    ['Артур', 'artur'], // Cyrillic
+    ['Борис', 'boris'],
+    ['Наталья', 'natalya'], // matches the live registered peer "natalya"
+    ['東京', 'dong-jing'], // CJK with syllable spacing
+    ['北京', 'bei-jing'],
+    ['Ω', 'o'], // Greek
+    ['naïve', 'naive'], // Latin diacritics
+    ['Köln', 'koln'],
+    ['Straße', 'strasse'],
+  ])('%j → %j', (input, expected) => {
+    expect(normalize(input)).toBe(expected)
+  })
+})
+
+describe('normalizeNameCandidate — slug rules', () => {
+  test('collapses non-alnum runs to a single hyphen and trims edges', () => {
+    expect(normalize('  a   b  ')).toBe('a-b')
+    expect(normalize('a___b...c')).toBe('a-b-c')
+    expect(normalize('--lead-and-trail--')).toBe('lead-and-trail')
+  })
+
+  test('caps length at 32 with no dangling trailing hyphen', () => {
+    const long = 'a'.repeat(40)
+    expect(normalize(long)).toBe('a'.repeat(32))
+    // a hyphen landing exactly at the cut must not survive as a trailing hyphen
+    const cut = `${'a'.repeat(31)}-bbb`
+    const out = normalize(cut)
+    expect(out.length).toBeLessThanOrEqual(32)
+    expect(out.endsWith('-')).toBe(false)
+  })
+})
+
+describe('normalizeNameCandidate — idempotency (normalize∘normalize === normalize)', () => {
+  test.each(['Café №2', '项目', 'My Project', 'Артур', 'boris', 'notifier-timer', '東京'])(
+    '%j is a fixed point of a second pass',
+    input => {
+      const once = normalize(input)
+      expect(normalize(once)).toBe(once)
+    },
+  )
+})
+
+describe('normalizeNameCandidate — fail-to-explicit edges (returned AS-IS, not mangled)', () => {
+  test.each([
+    ['', ''], // empty
+    ['①②③', ''], // non-transliterable circled digits → drop
+    ['😀', ''], // emoji → drop
+    ['---', ''], // only separators
+    ['2nd', '2nd'], // leading digit survives but is NOT a valid name
+    ['42', '42'],
+  ])('%j → %j', (input, expected) => {
+    expect(normalize(input)).toBe(expected)
+  })
+
+  test('edge results do NOT satisfy NAME_RE → caller fails-to-explicit', () => {
+    for (const bad of ['', '①②③', '😀', '---', '2nd', '42']) {
+      expect(isValidName(normalize(bad))).toBe(false)
+    }
+  })
+
+  test('valid goldens DO satisfy NAME_RE', () => {
+    for (const good of ['cafe-no-2', 'xiang-mu', 'my-project', 'iapeer', 'artur']) {
+      expect(NAME_RE.test(good)).toBe(true)
+    }
+  })
+})

package/src/core/normalize.ts

@@ -0,0 +1,89 @@
+// normalize — the SINGLE shared name normalizer (zone Идентичность):
+//   normalize(s) = slug(transliterate(s))
+//
+// The whole transliteration engine is isolated behind this one module so it can
+// be swapped (e.g. to a literal WASM-ICU binding) without touching any call site:
+// identity uses `normalizeNameCandidate` exclusively (re-exported from constants).
+//
+// ENGINE CHOICE (see _planning/normalizer-plan.md for the empirical comparison of
+// six engines against the zone goldens). The contract mandates ICU
+// `Any-Latin; Latin-ASCII`. Node/Bun `Intl` does NOT expose an ICU Transliterator,
+// and system `uconv`/`iconv` are forbidden by the zone (OS-nondeterministic) and
+// absent here. `transliteration` is the one pure-JS engine that reproduces ICU
+// across WRITING SYSTEMS — CJK → pinyin WITH syllable spacing (项目 → "Xiang Mu"),
+// Cyrillic (Артур → "Artur"), Greek (Ω → "O"), Latin diacritics (Köln → "Koln") —
+// and it bundles its own CLDR/unidecode-derived tables, so it is deterministic
+// across OSes (exactly the property the zone's iconv ban is protecting). It is the
+// deterministic CLDR-EQUIVALENT of ICU, NOT a literal ICU engine.
+//
+// Where `transliteration` UNDER-maps a SYMBOL versus literal ICU `Latin-ASCII`,
+// `ICU_LATIN_ASCII_SYMBOLS` realigns it (applied BEFORE transliterate). Seeded by
+// the golden `№`: the package maps it to "no" (and "№2" → "no2", GLUING the digit);
+// rewriting to ICU's literal "No." inserts a non-[a-z0-9] char that slug turns into
+// the required separator → "no-2". So the align fixes a missing SEPARATOR, not a
+// dropped punctuation mark (the package never emits one to "lose"). KNOWN LIMITATION:
+// only the writing systems listed above (CJK / Cyrillic / Greek / Latin-diacritics)
+// are verified-faithful to literal ICU; other scripts (Arabic / Hebrew / Korean …)
+// may diverge — no ICU oracle on host to measure — and symbols outside this map may
+// differ too. The map is extend-on-discovery; an unmapped symbol that transliterates
+// to nothing safely drops (→ fail-to-explicit downstream).
+
+import { transliterate } from 'transliteration'
+
+/**
+ * ICU `Latin-ASCII` alignment for the symbols where `transliteration` diverges
+ * from literal ICU. Deterministic CLDR-equivalent, NOT literal ICU; this map fills
+ * the symbol gaps. Extend by adding `<symbol>: <ICU Latin-ASCII output>` as
+ * divergences surface.
+ */
+const ICU_LATIN_ASCII_SYMBOLS: Record<string, string> = {
+  // № NUMERO SIGN. Package → "no" (and "№2" → "no2", gluing the digit). The literal
+  // ICU `Latin-ASCII` value is "No."; what makes the golden pass is the non-[a-z0-9]
+  // char between "no" and the digit (slug turns it into the separator → "no-2"). The
+  // trailing "." itself is dropped by slug — kept here only because it is ICU's exact
+  // output (mapping to "No-" or "no " would normalize identically).
+  '№': 'No.',
+}
+
+function alignIcuSymbols(value: string): string {
+  let out = value
+  for (const [symbol, ascii] of Object.entries(ICU_LATIN_ASCII_SYMBOLS)) {
+    if (out.includes(symbol)) out = out.split(symbol).join(ascii)
+  }
+  return out
+}
+
+// NAME_RE = /^[a-z][a-z0-9-]{0,31}$/ → at most 32 chars. slug bounds the length so a
+// long basename truncates deterministically. The LEADING-LETTER constraint is NOT
+// enforced here (a leading digit/hyphen result is returned as-is and the caller
+// fails-to-explicit) — the normalizer must never mangle a name to force validity.
+const MAX_NAME_LEN = 32
+
+/** slug: lowercase → every non-[a-z0-9] run → a single hyphen → trim edge hyphens
+ *  → cap length → drop a hyphen the length-cap may have left dangling. */
+function slug(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_NAME_LEN)
+    .replace(/-+$/, '')
+}
+
+/**
+ * normalize(s) = slug(transliterate(s)) — the shared primitive every name
+ * derivation/comparison routes through (basename(cwd) → personality, PEER_*
+ * comparisons, profile re-validation).
+ *
+ * IDEMPOTENT on already-valid names: normalize("boris") === "boris",
+ * normalize("notifier-timer") === "notifier-timer" — required because
+ * validatePersonality re-normalizes stored profile names.
+ *
+ * A non-transliterable / empty / leading-digit result is returned AS-IS (e.g.
+ * "①②③" → "", "2nd" → "2nd"); it will not match NAME_RE, and the caller
+ * fails-to-explicit ("create peer-profile.json explicitly") rather than the
+ * normalizer silently inventing a name.
+ */
+export function normalizeNameCandidate(value: string): string {
+  return slug(transliterate(alignIcuSymbols(value)))
+}