@aikdna/kdna-fidelity-core

KDNA

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: Beta — the current KDNA Asset Container and the local public-asset path are the stable public baseline. Licensed and remote access have public protocol contracts and evolving reference implementations; check release notes before production use. Hosted marketplace, billing, and AIKDNA-hosted loading are not part of the public baseline. See docs/maturity.md.

See KDNA in action — then create your own

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

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

→ Full 5-minute guide · Public reference display

What is a KDNA file?

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)
• optional signatures (signature.kdsig) — integrity and provenance attestations, 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.

What KDNA Core defines

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
• 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.

Authorization And Native Apps

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

• Authorization contract
• LoadPlan schema
• Runtime projection
• Import security
• Apple native runtime integration

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.

What KDNA Core does not define

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.

Official KDNA toolchain

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.

Component	Role	Source
KDNA Core spec	Format, schemas, runtime loading contract	this repo
KDNA CLI	Official command-line entry: inspect, validate, pack, unpack, load	this repo + @aikdna/kdna-cli
KDNA Loader	Official runtime loader for AI agents	packages/kdna-core/ + @aikdna/kdna-cli
KDNA SDK	Embeddable library for integrations	packages/kdna-core/
KDNA Eval	Experimental replay, budget, and consumption-evaluation primitives	packages/kdna-eval/ + @aikdna/kdna-eval

@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.

Examples

See:

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

Repository layout

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

Versioning

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.

Ecosystem

Repo	Package	Purpose
kdna-cli	@aikdna/kdna-cli	KDNA runtime CLI
kdna-studio-cli	@aikdna/kdna-studio-cli	AI-powered authoring CLI
kdna-studio-core	@aikdna/kdna-studio-core	Studio SDK for creators
kdna-skills	kdna-loader skill; @aikdna/kdna-mcp-server@0.4.2 (Experimental)	AI agent skill loader and MCP server
kdna-assets	—	Public asset releases
kdna-core-swift	Swift package 0.20.0	Apple-platform runtime
kdna-studio-swift	Swift package 0.4.0	Apple-platform authoring kernel; release recertification is pending
kdna-app-shared	Swift package 0.5.0	Shared Apple-app presentation infrastructure; release recertification is pending

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

License

Apache 2.0. See LICENSE.