Kotoba

Kotoba

A language AI agents can use, not abuse.

AI writes freely. Kotoba draws the boundary.

Kotoba is an intuitive, declarative, security-first language and computing stack for AI agents—and for humans who vibe-code with them.

Post-quantum cryptography is not an optional mode. It is the admission floor for every new Kotoba cryptographic boundary.

New confidentiality boundaries require hybrid X25519 + ML-KEM-768; new publication and package-admission boundaries require ML-DSA-65 alongside the current classical proof. Unknown suites, stripped PQ material, and classical-only downgrade fail closed. Development-only legacy paths are not a compatibility target and do not define the Kotoba security model.

Existing software adds security around the program. Kotoba makes security a property of the whole computation.

This repository contains the installable Kotoba CLI and implementation. A compiled program can use only the authority it was granted: no implicit filesystem, network, process, clock, model, or secrets. Unsupported or unverifiable behavior fails closed. This is a confinement direction, not an “unhackable” claim; runtime and OS isolation remain part of the trusted computing base.

Language contract: kotoba-lang/kotoba-lang · site: kotoba-lang.org

The bundled standard-library pilot uses kotoba.coll, kotoba.spec, and kotoba.json IDs, with explicit old-name aliases. See lib/ for source layout and portable verification, and the library and Lexicon event design. Amu and other execution/contract owners remain separate repositories.

Common foundation and Awai distribution

Kotoba is the reusable language/tooling foundation. Amu owns compilation and Kototama owns common execution/state/authority-budget/receipt contracts. AIUEOS is the common OS; AWAI OS is its Awai Network distribution, maintained in the same kotoba-lang/aiueos repository with the same kernel and ABI. network-awai owns the distributed network and Awai-specific product composition. See the distribution decision.

Distribution choice does not change language/VM semantics, confer capability or node membership, or qualify a release. Awai Node and Itonami also have independently qualified paths on other hosts. Common fixes stay in their existing owners; Awai presets do not create another language or OS fork.

Try Kotoba with Amu

On an Apple Silicon Mac, use the native Mac ARM64 first-run guide. Amu's bin/amu, bin/kotoba and bin/kotoba-compiler are native ARM64 Mach-O entries. The guide checks image digests and signatures, then checks, compiles, packages and executes a small program returning 42 and 43 with an explicit directory scope. No Linux VM, hosted runtime, account, model download or payment is required.

Linux users can use the pinned Linux starter for its separate fuel/capability controls. Current Linux x86_64 entries have explicit *-linux-x86_64 names; the immutable starter snapshot retains its original names. The Linux ARM64 diagnostic guide and Mac first run each state their own limited qualification. A successful first run does not qualify the complete runtime or an independent-user release.

This repository's bin/kotoba still dispatches to retired KBB/Clojure host routes. Do not use that source launcher for the native first run or install a hosted runtime to work around a refusal. The former Homebrew and kotoba -e quick start is not the native starter. The CLI examples below describe separate implementation contracts; full native CLI command parity and the older package's qualification remain open. Keep the first run on the single pinned Amu entry above.

Web3 identity starts from a chain-neutral Kotoba principal controlled by a Passkey. EVM smart accounts are explicit CAIP-10 links verified by ERC-1271 or ERC-6492 when counterfactual; neither Base nor any provider is the identity root. No private key or seed crosses this CLI boundary, and authentication does not grant an agent authority without a separately scoped capability.

kotoba id new
# browser opens → approve with Passkey → verified username + Stable Principal saved locally

kotoba id show

kotoba id new \
  --account eip155:8453:0xA00366234D29d4F882088048c0B2fa0dB7302D4E

auth.kotoba.cloud is the automatic canonical RP; no username or RP input is required. The CLI uses a ten-minute, single-use device authorization request. The Passkey ceremony and browser session remain on auth.kotoba.cloud; the CLI receives only {username, principalId, accountDid, activeDid} and stores that public projection at ${XDG_DATA_HOME:-$HOME/.local/share}/kotoba/principal.edn. It does not mint an unrelated local UUID and never receives a Passkey private key, wallet seed, browser cookie, or long-lived bearer token. A non-canonical --rp-id is refused before the browser opens.

Holding your own DID update keys

The account DID did:webvh:<scid>:auth.kotoba.cloud:tenant:<user> is a hash-chained, signed log. By default its update keys are custodied by the identity service. These commands move them to this machine, after which the service can host the log but can no longer change it:

kotoba id take-custody --recovery-out /Volumes/offline/kotoba-recovery.edn
# generates active / next / recovery Ed25519 keys HERE and prints a CODE.
# Open the fixed page it names, signed in with your Passkey, TYPE the code,
# approve with the Passkey. After the host's delay the CLI checks that the
# published handover is exactly the proposed entry, pins it, and writes a
# handover attestation signed by your key -- publish that file.

kotoba id rotate [--also-known-as did:…,did:…]   # sign the next entry with the pre-committed next key
kotoba id recover --recovery /Volumes/offline/kotoba-recovery.edn \
                  --recovery-out /Volumes/offline/kotoba-recovery-2.edn
                                 # also works on a new machine: the recovery file records its
                                 # handover, and a log forked there is refused
kotoba id verify --did did:webvh:… [--pin <versionId>] [--attestation handover.json]

The handover entry lists your active key in updateKeys and commits, by hash only, to your next and recovery keys (nextKeyHashes). From then on the did:webvh pre-rotation rule means only a pre-committed key can sign the next entry; the service's keys were never committed, so an entry it signs fails every resolver. The CLI refuses a handover that differs in any way from the entry it expects (another key, a service endpoint, watchers, a witness) and builds every later document from the same allowlist (pinned @context, your own alsoKnownAs, your key). The code (XXXX-XXXX-XXXX) is bound to your account.

State lives in ${XDG_DATA_HOME:-$HOME/.local/share}/kotoba/webvh-custody/, one file per DID (mode 0600, created private, written atomically, with a lock per DID); the recovery key goes to its own file -- keep it offline. Losing both the next key and the recovery key freezes the DID: nobody, the service included, can update it again. Every fetch checks that the served log is the one its URL names and extends the version this machine pinned, so a host that rolls back or forks the log is reported (:id/log-fork-detected) and nothing is signed on top of it. verify labels custody :holder-pinned only when a pin or the holder's attestation confirms the handover independently of the host; otherwise :holder-unpinned, with the fork risk spelled out.

Base remains a useful Murakumo settlement link, but it appears only when eip155:8453 is supplied. kotoba id account --address 0x… --chain-id 1 describes a compatibility account alias; it never replaces the principal.

kotoba identity new remains an explicit Ed25519 operator-key command for IPNS namespace and artifact signing. It is not the default human login ID.

An empty policy denies every host effect, including :host/http. Hosted billed deploy of those grants is not live. Wasm Component is the primary portable profile. The compiler CLI defaults to the host native target; browser/Worker builds select their Wasm target explicitly. Bounded native AOT (x86-64/AArch64) still requires admitted capabilities; an ambient OS process is not the application execution model.

The persistent Datalog database is kotoba-lang/kotobase, not this repository.

The rest of this file is the implementation contract.

Where this fits / quick use

Figure: an interactive map of the kotoba / murakumo stack (published from the same figure as this section; the page may not be live yet).

Two layers sit beside this path and are not part of it yet:

• Private network layer: AWAI DNA (spec in network-awai/network-awai-apex PR #14, branch dna-private-network-spec, directory awai-dna/): the DNA CID is the network id, each agent keeps a signed source chain, with warrants and a kekkai realm. Proposed / spec stage, open PR, simulated transport only. There is no "awai chain".
• Settlement: Base / x402 settles bounded USDC charges for murakumo's public paid route (cloud-murakumo). Base is a settlement link, not the identity root. Chain ID 260425 (cloud-itonami/chain-contracts) is decommissioned and is not live.

Quick use (this repo; commands as documented below in Install and Quick start):

brew tap kotoba-lang/kotoba && brew trust kotoba-lang/kotoba && brew install kotoba
kotoba -e '(+ 1 2)'
kotoba id new          # opens a browser; approve with Passkey; saves the public principal projection locally
kotoba id show
kotoba check --kind cli-contract --json   # validate the CLI/package/lock contract

kotoba id new never receives a Passkey private key, wallet seed or bearer token, and authentication alone grants an agent no authority. Running jobs (itonami), nodes and gateways (murakumo), and result storage (kotobase) live in their own repositories; see kotoba-lang/murakumo for the node and job commands.

Not live or guaranteed: hosted billed deploy of kotoba grants; the AWAI DNA network; anything on chain ID 260425.

Lisp machine architecture

AiueOS is the OS for a modern Kotoba Lisp machine in development. Kototama is its implementation-independent Lisp VM contract: closed S-expression computation, IPLD state, bounded authority and content-addressed receipts. Amu checks and compiles code; grant decides permission; runtime hosts and OS mechanisms enforce the admitted boundary. Kototama also has hosted engines and does not require AiueOS for every execution.

The stack architecture separates responsibility, source/library and artifact dependencies. Its composition contract routes to each owner's specification; it is not a new language or runtime semantics. "Modern Lisp machine" describes the architectural direction. It does not certify a complete integrated debugger, live system modification, full heap image restore, selfhost compiler or physical-machine qualification.

Purpose and philosophy

Kotoba is designed first for software written, changed, tested, and operated by AI agents and by people directing them. That includes autonomous coding loops and vibe-coding workflows, where intent may arrive as natural language and the generated program must still cross a deterministic safety boundary before it can act. Source, dependencies, checked KIR, target artifacts, tool requests, and observed external content are treated as untrusted inputs—not as authority.

The priorities are:

1. Safety before ambient convenience. Effects, capabilities, resource budgets, package identities, and deployment authority are explicit and deny-by-default. Unsupported or unverifiable behavior fails closed.
2. A short, reproducible agent loop. Machine-readable contracts, one checked KIR shared by qualified backends, bounded compiler workers, deterministic caches, target-aware tests, and signed receipts make develop → check → test → deploy cycles fast to repeat and cheap to audit. Performance claims remain workload- and host-specific rather than universal.
3. Cryptographic trust with precise scope. CID-pinned inputs, signatures, trust/revocation policy, artifact seals, and execution receipts protect integrity and provenance. Encryption, decryption, key use, and secret access occur only through explicitly granted, purpose-bound capabilities and a qualified provider; Kotoba does not claim that every source file or value is automatically encrypted.
4. White-hat use. The language and its tooling are intended for authorized construction, defense, verification, repair, and auditable automation—not for bypassing controls or acquiring hidden authority. This philosophy guides the project; enforceable safety comes from the capability/effect/resource boundary rather than from trusting an agent's stated intent.

Design influences

These are influences on particular design choices, not claims of source or runtime compatibility:

• Lisp and Clojure — homoiconic, data-oriented programs; immutable values; a small composable language; and interactive development.
• Rust — compile-time safety discipline and affine handling of authority. Kotoba is benchmarked against Rust's safety model; it does not copy Rust's general ownership/lifetime system.
• Deno — secure-by-default execution with explicit permission boundaries.
• Unison — semantic, content-addressed definition identity and codebase operations independent of mutable file names.
• Ethereum and CACAO — signed identity, attenuated delegation, and verifiable authorization/receipt boundaries, without implying EVM compatibility.
• IPFS — CID-addressed, byte-verified discovery and distribution.
• Nix — pinned inputs, declarative environments, reproducible artifacts, and the principle that deployment should consume the same admitted closure that was tested.

Stack topology

Public service domains

kotoba.cloud is the CLI's public control, identity, and deploy-discovery entrance. It deliberately does not collapse the services it coordinates:

• kotobase.net persists artifacts, state, and receipts;
• murakumo.cloud places and executes CPU/GPU work;
• itonami.cloud carries agent work: workspaces, goals, tools, and approvals; and
• kotoba-lang.org remains the language, specification, and conformance surface.

The machine-readable contract is /.well-known/kotoba-cloud.json. Discovery is not ambient authority: each deploy receipt records the origins separately and the CLI refuses a profile whose pinned role assignments drift.

The current topology separates library dependencies from generated artifacts: this CLI imports Amu and Kototama; Kototama and AiueOS import grant for permission decisions; the booted OS consumes verified compiler artifacts. The database is a separate data plane. This repo's language-authority and naming cleanup decisions are recorded in docs/ADR-stack-topology-and-design-cleanup.md (root authority: com-junkawasaki/root ADR-2607241100).

Repository boundary

kotoba-lang/kotoba is the language and library substrate. Keep generic protocols, data structures, compilers, runtimes, storage, crypto, and reusable fixtures here. The split policy is recorded in docs/ADR-repository-boundaries.md.

kotoba-lang/kotoba-lang owns the standalone language and public CLI contract. This repository keeps host implementations, integration tests, and legacy Rust adapters while they are migrated to consume the CLJC/EDN authority there.

The Rust kotoba crate/CLI is an integration adapter over multiple workspace crates. It is no longer the semantic authority for the public CLI. New command shape belongs in kotoba-lang/kotoba-lang, and host launchers should delegate to that CLJC contract.

kami-engine is the strongest future split candidate when the Kami host, rendering/devtool SDK, templates, and golden UI verification can build without kotoba-kotodama path dependencies. After that split, this repository should keep only thin WIT/component fixtures and integration tests for Kami surfaces.

Domain actors do not belong in this repository. They live in etzhayyim/com-etzhayyim-* as .cljc actors/cells. AT Protocol actors, PDS/AppView handlers, and XRPC application surfaces live in gftdcojp/app-aozora. Hosting, placement, fleet, gateway, and runtime operations live in kotoba-lang/murakumo.

The historical crates/kotoba-kotodama tree (and the rest of crates/) has since been removed from this repository entirely (604896171b, 2026-07-01); domain cells, Python UDF pools, AT Protocol actors, and hosting code moved to their canonical owners per the boundary above.

📺 Explainers & Docs site

A static documentation site (landing page + two interactive, auto-playing explainer videos with Japanese narration) lives under docs/ and is published via GitHub Pages:

🌐 kotoba-lang.github.io/kotoba