Akashic

A git-native, language-agnostic contract/schema platform. Define your contract primitives — objects, enums, errors, localizations, constants, routes, events, well-known types — once, in a normalized language-neutral model; version them as git-friendly NDJSON; resolve them with a fast memoized engine; and generate real per-language packages that other teams install.

Producer runs akashic to EMIT a native package; consumers just install it — they never run akashic.

contracts (NDJSON source, git)  ──►  resolve (memoized O(n+e))  ──►  generate installable package
        git-versioned                  structural sharing               per language, native deps

Language targets

TypeScript (zod), Python (pydantic), Rust (serde), Go (stdlib), Dart (SDK), Java (JDK-only), Kotlin (stdlib-only) — all seven shipped and full: core contract + HTTP client + socket channels + runtime constraint enforcement + the byte-identical cross-language wire envelope. The Java/Kotlin generators use no reflective JSON library (hand-ordered JSON), so plain javac / kotlinc prove byte-identity — see docs/breakdown/generators.md for the interop toolchain matrix.

Quick start

bun install

# Build the bundled example contract into examples/contracts/example/dist/
bun run src/cli/index.ts build examples/contracts/example

# Build a project to a custom output directory
bun run src/cli/index.ts build examples/contracts/zeus --out zeus-out-ts

# Pick a target language
bun run src/cli/index.ts build examples/contracts/zeus --lang python --out zeus-out-py

# Scaffold a fresh project, then build it
bun run src/cli/index.ts init my-contracts
bun run src/cli/index.ts build my-contracts

build reads the NDJSON source, validates it, resolves the graph, writes the binary cache, and emits an installable package (default target TypeScript, under dist/ts/). See docs/breakdown/build-pipeline.md.

Bundled examples

• examples/contracts/example/ — a small synthetic contract exercising every feature.
• examples/contracts/zeus/ — a hand-translated slice of a real production contract set.
• examples/contracts/apple/ — a peer project in two versions, for multi-version imports.
• examples/typescript/thunderbolt/ — a runnable TS consumer of the generated @akc/zeus package.
• examples/python/consumer/ — a runnable Python consumer.
• examples/interop/ — cross-language byte-identical wire proofs.

Details: docs/breakdown/examples.md.

Module map

path	role
src/model/	the locked contract types, builders, and a structural validator
src/store/	NDJSON (git source) + sharding + the derived binary cache
src/resolve/	the resolver, reverse index, and incremental re-resolve — the core engine
src/codegen/	the Generator interface + seven generators (TS/Python/Rust/Go/Dart/Java/Kotlin)
src/imports.ts	cross-project import resolver — bundle mode, closure-only vendoring
src/import/	inbound schema importers — jsonschema.ts (JSON Schema -> Model), openapi.ts (OpenAPI 3.x -> Model + services, reuses the JSON Schema importer for components.schemas)
src/cli/	the init / build / import command-line entry point
src/project.ts	akc.yaml config + the end-to-end build pipeline
src/index.ts	the public programmatic API
test/	unit + conformance tests on the safety-critical paths
examples/	contracts, per-language consumers, cross-language interop proofs

Documentation

Full docs live in docs/:

• docs/design/ — the WHY: git-as-substrate, two-layer model, null-only semantics, the locked schema, the resolve engine, storage format, measured evidence, positioning vs protobuf/gRPC.
• docs/breakdown/ — the WHAT/WHERE: module map, build pipeline, record kinds, the five generators, tests, examples, roadmap.
• docs/integrations/ — WITH THIRD PARTIES: installing & using the generated package, HTTP client + transports, socket channels + adapters, cross-project git imports, well-known types.

Development

bun run tsc     # type-check (must pass clean)
bun run test    # unit + conformance tests