Pre-release ecosystem — contract and narrative correction in progress

KDNA is a judgment-asset container and ecosystem. This repository owns the protocol and Core runtime; companion repositories provide creation, consumption, authorization, Apple, Web, Agent, editor, and developer integrations. Existing packages are pre-release snapshots, not Beta, stable, GA, or a reason to retire an integration's mission.

KDNA gives reusable judgment its own identity and lifecycle.

KDNA is an open judgment-asset format and protocol. Individuals, teams, Agents, and tools can create bounded judgment assets whose versions, provenance, access, projections, and evidence can be managed independently from any one Prompt, Skill, model, or application.

Judgment can also remain in those carriers. Prompts and Skills can be structured, versioned, tested, and reused; RAG and knowledge systems can store or retrieve judgment. KDNA adds a standard asset and loading contract when the judgment needs to move independently. Equivalent content may produce the same behavior in another carrier, and KDNA does not claim otherwise.

Anyone can create a KDNA asset. KDNA Core validates structure, integrity, provenance, and authorization facts; it does not decide whether the judgment is true, good, expert, or worthy of publication. Creation and compatible Agent consumption use the KDNA toolchain contract: inspect → plan-load → authorization → load/project → Runtime Capsule. Directly unpacking or decoding asset internals is not a compatible Agent consumption path.

New to KDNA? → Start Here

What IS KDNA, fundamentally? → Core Narrative and Boundaries

When does KDNA add value beyond an existing Prompt or Skill? → Why KDNA · KDNA and the AI Stack

Building a consumption runtime? → Consumption Runtime

Roadmap and contribution guide → Public Roadmap

This repo defines KDNA Core — the file format, schemas, and runtime loading contract. The official KDNA toolchain is published from this repo and its companion packages.

Maturity: Pre-release — the container, toolchain, and integrations are being reconciled against their exact public contracts. Component maturity varies and must be stated per repository and version; no integration is declared valueless merely because it is outside one release wave. Check the exact version's schema, specification, fixtures, conformance, and release notes before use. See docs/maturity.md.

Generate a current-format demonstration locally, load its Runtime Capsule, and then replace the demonstration judgment with your own.

npm install -g @aikdna/kdna-cli

# Step 1: generate and package a current demonstration asset
kdna demo judgment ./judgment
kdna pack ./judgment ./judgment.kdna

# Step 2: verify the loading contract and receive a Runtime Capsule
kdna validate ./judgment.kdna --runtime
kdna plan-load ./judgment.kdna --json
kdna load ./judgment.kdna --profile=compact --as=json

Official package coordinates: all official npm packages are published under the @aikdna scope (for example @aikdna/kdna-cli and @aikdna/kdna-core). The bare kdna name on npm is an unrelated third-party placeholder — do not install it. On PyPI, the kdna project name is likewise an unrelated third-party placeholder, not ours. Our official Python distribution on PyPI is aikdna (the import package name remains kdna). Install only aikdna from PyPI — never pip install kdna. See SECURITY.md.

The AIKDNA asset repository currently displays two current-format technical reference assets and zero Clusters. Listing is not an endorsement, and the local demonstration above remains the recommended first-run path.

→ Full 5-minute guide · Public reference display

A .kdna file is a single, portable container that holds:

• a public manifest (kdna.json) — the asset's identity and metadata
• a judgment payload (payload.kdnab) — the actual structured judgment data
• optional encryption for licensed entries — encrypted judgment payload with in-memory-only decryption (current in JS Core/CLI); optional watermarking (future)
• an optional signature (signature.kdsig) — an Ed25519 signature bundle (kdsig.ed25519, RFC-0021 M1) over the canonical content digest; verified offline and fail-closed during validation and loading. It attests integrity and provenance, not content endorsement
• version and lineage information — for traceability across releases
• a runtime load contract — describes how the official KDNA loader may read the asset
• optional attachments — supplementary files referenced from the payload
• an optional checksums file — per-entry digests for integrity checks

.kdna files are produced by authors through the KDNA toolchain and consumed by the KDNA loader. The format itself is content-neutral — KDNA Core does not rank judgment quality or endorse specific assets. Agents can create .kdna files through the official SDK; any file that passes kdna validate is a valid KDNA asset.

Core format validity and Creation Engine acceptance are separate results. An official Creation Writer emits checksums.json and explicit scoped authoring semantics, but those stricter writer requirements do not redefine the minimum Core format. See Creation Output Boundary.

A .kdna asset can carry an optional signature.kdsig bundle (kdsig.ed25519, RFC-0021 M1). The Ed25519 signature covers the canonical content digest (CANONICALIZATION.md), verification is fully offline, and loading is fail-closed: an asset whose signature does not verify is rejected, never downgraded to "unsigned".

const {
  generateSigningKeyPair,
  signKDNA,
  verifyKDNASignature,
} = require('@aikdna/kdna-core');

// Author side: sign a packaged asset (keep the private key secret).
const key = generateSigningKeyPair();
const signed = await signKDNA('./judgment.kdna', key.private_key, {
  outputPath: './judgment.signed.kdna',
});

// Consumer side: verify offline. Throws on any verification failure.
const evidence = await verifyKDNASignature('./judgment.signed.kdna');
// evidence.state === 'verified', evidence.key_fingerprint, evidence.content_digest

// Pin the signer key to reject signatures from any other key:
await verifyKDNASignature('./judgment.signed.kdna', {
  expectedPublicKey: key.public_key,
});

Unsigned assets stay valid and report state: 'absent'; callers can require a signature instead. A valid signature proves integrity and key-bound provenance only — it never proves the judgment is correct, expert, or safe. The Python SDK (python-sdk/) signs and verifies the same wire contract, and both implementations share the deterministic known-answer vectors under conformance/signature/.

KDNA Core is the format authority. It defines:

• the file format (container layout, mimetype, required entries)
• the manifest schema (kdna.json shape and required fields)
• the current payload profile schema
• the encryption profile for licensed entries (AEAD envelope over payload.kdnab)
• the signature and digest metadata used for integrity and provenance (canonical content digest; the kdsig.ed25519 asset signature profile of RFC-0021 M1)
• the version chain metadata (lineage, judgment version, compatibility)
• the runtime loading contract (load profiles, decryption requirements, token hints)

KDNA Core is also the toolchain reference. The recommended way to produce, validate, load, and consume .kdna files is through the official KDNA toolchain.

Protected, licensed, remote, and native-app loading behavior is specified here:

• Authorization contract
• LoadPlan schema
• Runtime projection
• Import security
• Apple native runtime integration
• SPEC-INDEX: every normative specification

Ordinary Core loading remains fail-closed for access: "remote". Self-hosted Runtime deployers that control the packaged server-side asset use the explicit @aikdna/kdna-core/remote-runtime package subpath to obtain one full Capsule for server-side projection. That API is not a client loading shortcut, an identity or entitlement service, a content-confidentiality mechanism against the deployer, or an AIKDNA-hosted endpoint. See Remote access.

KDNA Core is content-neutral. It does not define:

• content quality — what judgment is correct, complete, or high-value
• author trust — whether an author is credible or endorsed
• official recommendations — which assets should be used in production
• distribution — how third parties host, list, recommend, or sell assets
• runtime policy — what a loader should do with an asset at runtime (block, allow, warn)
• content governance — moderation, takedown, ranking, certification

KDNA Core also does not make an experimental routing or composition decision part of the asset format. Applications may exchange route cards, consumer indexes, traces, and evaluation evidence as versioned sidecars. Those artifacts describe how an asset was considered for a task; they do not change the asset's judgment payload or make a recommendation on behalf of KDNA Core.

These are concerns of external platforms and policies. KDNA Core supplies the verifiable primitives and the official toolchain (as a reference implementation); everything else is out of scope.

The recommended integration path is through the official SDK, CLI, Loader, or API. Third-party runtimes are compatible when they implement the LoadPlan, authorization, integrity-verification, and Runtime Capsule contracts. Passing format validation alone does not make a raw decoder an Agent runtime.

The official KDNA toolchain is published from this repo and its companion packages. The KDNA Core format and the official toolchain are versioned together; deviations between the spec and the official implementation are bugs.

The direct-file validate → plan-load → load path is the current recommended Agent-facing technical path. The historical global package-store and auto-discovery Skill experience is not a protocol requirement and is under product recertification; it must not be treated as the default KDNA user model.

@aikdna/kdna remains a maintained compatibility bridge. New integrations should install @aikdna/kdna-cli and @aikdna/kdna-core directly. The complete package, source-only application, and release-artifact inventory is published in the schema-2 ecosystem manifest.

See:

• examples/minimal/ — the smallest valid authoring source layout for producing a .kdna file
• fixtures/ — conformance and test fixtures

kdna/
├── packages/             # kdna-core (loader), kdna-eval (scoring harness)
├── schema/               # JSON Schemas for manifest, payload profile, checksums, ...
├── docs/                 # Spec, architecture, guides
│   ├── core/             # Core format and runtime-contract docs
│   ├── tools/            # Per-tool documentation
│   ├── examples/         # Example guides
│   └── guides/           # How-to guides
├── examples/             # Authoring source layouts used to produce `.kdna` files
├── fixtures/             # Conformance test fixtures
├── conformance/          # Conformance test runner
├── rfcs/                 # Accepted and proposed RFCs
└── specs/                # Normative specifications

Toolchain packages follow SemVer 2.0. Package versions are release identifiers, not competing KDNA product formats. There is one current KDNA Asset Container; technical compatibility identifiers such as format_version are defined by the schemas and specification. Breaking protocol changes require an RFC and an explicit migration path.

Machine consumers should use ecosystem-manifest.json instead of inferring one package per repository.

Apache 2.0. See LICENSE.