KDNA Studio Core

Status: The Creation Engine described below is an unreleased dirty-source candidate. The npm latest package does not contain this candidate API. Source tests and candidate tarballs are not publication, clean-install or compatibility evidence.

KDNA Studio Core is the JS authoring kernel for .kdna files. It turns scattered notes, documents, works, and feedback into loadable judgment assets by distilling stable judgment patterns into a declared domain and loading scope.

Open-source Studio-compatible authoring kernel for creating reviewable .kdna assets — JS/npm package. Supports two authoring paths: interview-first (direct expression) and distillation-first (pattern extraction from existing content). Both end with the current canonical KDNA runtime export.

KDNA Studio Core is the JS authoring kernel. It is not a UI tool and not a CLI package. It is a pure-logic engine for creating KDNA judgment cards, optional provenance records, compiler output, and runtime .kdna exports from JavaScript applications and Studio-compatible tools.

Studio-compatible tooling uses a project workspace for authoring, review, and audit, then exports the canonical KDNA runtime container. The public asset is the packaged .kdna file; project JSON is an authoring/editing view, not the default distribution form.

Studio Core distinguishes authoring compile output from runtime distribution output. Authoring compile output may include source entries such as KDNA_Core.json and KDNA_Patterns.json for audit and review. Runtime export must produce the canonical KDNA distribution shape:

mimetype
kdna.json
payload.kdnab
checksums.json

Runtime export must validate with @aikdna/kdna-core and must plan through the LoadPlan contract in aikdna/kdna. Studio products must not create app-private .kdna shapes that KDNA Core or CLI cannot inspect, validate, or plan-load.

The 3.x authoring API provides the minimum explicit path source -> review -> confirm -> export while retaining the admitted project, card, evidence, compile, distillation, provenance, and Runtime export primitives. Every judgment on this path declares whether its source is human, organizational, AI, Agent, or mixed. If synthesized content claims to represent a named person or organization, export fails until the matching subject is recorded as confirmed.

Current exports keep responsibility names separate from compatibility coordinates: the container uses format_version: 0.1.0, the payload declares profile: kdna.payload.judgment with profile_version: 0.1.0, checksums use digest_profile: kdna.digest-basis.runtime-entry-set with digest_profile_version: 0.1.0, and Runtime loading yields a kdna.runtime-capsule contract at 0.1.0.

| Library | Language | Role | |---------|----------|------| | @aikdna/kdna-cli | JS/npm | Operate KDNA — inspect, validate, plan-load, pack/unpack, load | | @aikdna/kdna-studio-core | JS/npm | Authoring kernel — project model, cards, review/provenance, compiler, runtime export | | @aikdna/kdna-studio-cli | JS/npm | Create via CLI — kdna-studio create, review, export | | @aikdna/kdna-core | JS/npm | Use KDNA — load, validate, format |

What it does

• Project Model — studio.project.json with full metadata, provenance tracking
• Evidence Room — import raw material (text, markdown, interviews, cases)
• Distillation Target — declare domain category, owner scope, granularity, task scope, include/exclude areas, and load condition before extraction
• Evidence Relevance — classify source material as relevant, weakly relevant, out-of-scope, or split-domain before distillation
• Scope Gate — mark candidates with scope_fit, relevance score, and suggested split domain before they can become cards
• Judgment Cards — 16 schema-authoritative card types spanning principles, boundaries, risks, scenarios, reasoning, terminology, and evolution.
• Review and provenance — AI may propose candidates; projects can record review and release evidence when needed.
• Authoring Provenance — every compiled manifest records Studio-compatible compiler metadata, project digest, review counts, and confirmation status.
• Asset Build Reports — every compile emits build, provenance, review, and receipt artifacts for audit.
• Compiler — complete, non-deprecated cards → authoring compile output; optional Human Lock provenance is preserved
• Runtime Export — compiled judgment → canonical mimetype + kdna.json + payload.kdnab + checksums.json
• Declared Judgment Core — optional judgment_core fields (highest_question, worldview, ordered value_order, and bounded judgment_role) are preserved verbatim from project source through compile and runtime payload. They are scoped judgment data, not facts or policy.
• Semantic Fidelity — source references, core_structure relations, extended reasoning fields, generic pattern subtypes, and source-authored evolution survive Runtime export without being reduced to a field allow-list. Human Lock fingerprints cover the complete authored field tree.
• Provenance — content fingerprinting, build tracking, audit trail
• Creation Engine candidate — an unreleased, UI-independent state machine that guides terminal Agents from purpose and untrusted source material through elicitation, confirmation, semantic tests, repair, and accepted project compile.

What it is not

• Not a UI framework
• Not the official KDNA Studio App
• Not a one-click AI generator
• Not a prompt engineering tool

Authoring Flow

Evidence Room → Judgment Cards → Review/Provenance → Compile → Validate → Export

For distillation-first authoring, the flow starts with an explicit target:

Declare Domain + Scope → Import Evidence → Classify Relevance → Distill Candidates
  → Scope Gate → Review → Promote to Cards → Provenance → Compile → Export

A single .kdna asset should stay scoped to one domain and loading condition. If a task needs several judgment domains, create multiple domain assets and use an explicit, separately admitted Host contract rather than making one broad file. Route cards and consumer indexes are historical advanced sidecars under recertification; they do not belong in the runtime asset export.

Creation Engine

The public creationEngine module is the terminal-Agent creation contract. It does not require the Studio App:

const { creationEngine } = require('@aikdna/kdna-studio-core');

let workspace = creationEngine.createWorkspace(null, {
  mode: 'agent-authored',
  workflowMode: 'autonomous',
  access: 'public',
  createdBy: { type: 'agent', id: 'terminal-agent' }
});

workspace = creationEngine.setPurpose(workspace, {
  objective: 'Keep generated titles to eight words or fewer.',
  scope: 'headline drafting',
  non_goals: ['Do not shorten quoted titles.'],
  loading_condition: 'Load while drafting a new headline.',
  global_boundaries: ['Quoted titles remain unchanged.']
});

console.log(creationEngine.nextAction(workspace));

All mutations return a new workspace. saveWorkspace atomically persists 11 digest-bound JSON artifacts. Public validation and loadWorkspace enforce the shipped JSON Schema, reject mixed or schema-invalid snapshots with useful JSON-pointer paths, and recover a complete interrupted replacement. Private source bodies are never stored in the materials index or copied into Runtime output. Source text is untrusted data; detected instruction-like text creates a blocking safety question. Optimistic save concurrency rejects stale or divergent Agent snapshots instead of silently losing a newer handoff. Source-grounded work may start from a structured, digest-bound interview answer by an explicit actor. reviewMaterial supports either a classification change or an honest reviewed-no-change receipt while keeping source identity, bytes, time, trust scan, and sensitivity immutable. The private operation ledger binds each write ID to its canonical request digest: exact retry is inert only while its semantic coordinate remains current, and conflicting or stale ID reuse fails closed without changing semantic revision or Runtime output. Export uses private prepared → verified → completed receipts so a fresh process can resume the exact verified encrypted bytes after termination rather than regenerating or substituting an asset.

Runtime access: public means possession of the file is sufficient to load it; it does not publish the file. Sensitive source handling, material processing, Runtime access protection, output-disclosure review, and later distribution are separate private decisions.

Execution (collaborative or autonomous) is separate from the five authority modes: agent-authored, human-confirmed, organization-confirmed, interpretive, and mixed-authorship. Human participation is a receipt, not an authority mode. Representation receipts stay in private Creation evidence and cannot become Runtime creator identity, Human Lock, or public human-confirmation evidence.

Semantic-test acceptance binds both the judgment semantic digest and a canonical digest of the complete evaluated test report. Adding or re-evaluating a case invalidates the old acceptance until an allowed actor re-accepts the current report. Optional comparison cases model an explicit with-KDNA versus without-KDNA run for the same task and bind the expected judgment difference to specific units. Candidate review receipts retain digest-bound before/after facts, including an honest no-change review. An autonomous interpretive workspace may be accepted by an independent evaluator Agent without treating that evaluator as the source author. The creating Agent may not self-accept.

Official Creation completion is stricter than judgment acceptance or export: JUDGMENT_ACCEPTED, FORMAT_VALID, and APPLICATION_VERIFIED must bind the same semantic revision/digest and exact final asset bytes. compile_ready means only readiness to build a managed candidate. Application verification uses post-FORMAT_VALID, build- and asset-bound fresh-hidden free-response tasks plus distinct Ed25519 Consumer/evaluator keys. Core verifies the signatures and mechanically derives adoption fidelity, zero safety/permission/ external-action/over-application violations, and direction stability rather than accepting a caller-provided pass or requiring a model-quality gain. Signatures attest key possession, not real-world identity or role independence, so Hosts retain separate isolation evidence. The official Host hides this plumbing from ordinary users. These private workflow fields and receipts never enter Runtime.

See Creation Engine contracts for the complete object model, state machine, acceptance rules, persistence contract, compile mapping, and independently verified build receipt.

Public package boundary

The npm package exposes the supported authoring path and its project, card, evidence, compile, provenance, distillation, and Runtime export primitives. Test Lab, Feynman, Quality, and Governance workshop implementations remain in the repository for research and regression coverage. They are not exported from the package root and are not included in the release tarball. Their code retention is not a compatibility promise.

This boundary begins at 3.0.0 because it removes root exports and deep-import paths that existed in the published 2.x package. Consumers of the published 2.0.2 contract must not be silently moved to 3.x. See the changelog for the complete breaking-export and packaged-path inventory.

Install

npm install @aikdna/[email protected]

That command installs the published incumbent. The 3.0.0 contract described above is an unreleased source candidate and must not be inferred from the npm latest tag.

Migrating from @aikdna/[email protected] is a source migration, not a drop-in package rename. Follow the package migration guide for the verified registry boundary and required code changes.

Studio CLI

The command-line authoring entry is a separate package:

npm install -g @aikdna/[email protected]
kdna-studio create my_domain --name @yourscope/my_domain
kdna-studio import my_domain ./notes.md
kdna-studio target declare my_domain \
  --category expression_writing \
  --scope personal \
  --granularity core_principles \
  --task "longform article review" \
  --include "argument structure,tone,revision" \
  --exclude "life habits,food preference"
kdna-studio source classify my_domain
kdna-studio distill my_domain --candidates candidates.json
kdna-studio candidate accept my_domain <candidate-id>
kdna-studio candidate promote my_domain
kdna-studio card add my_domain axiom \
  --field one_sentence="Judgment principle" \
  --field full_statement="What the agent should do differently" \
  --field why="What fails without this judgment" \
  --field applies_when='["Relevant task"]' \
  --field does_not_apply_when='["Out of scope"]' \
  --field failure_risk="What could go wrong"
kdna-studio card approve my_domain <card-id> --by expert --statement "I confirm this judgment."
kdna-studio export my_domain --out dist/my_domain.kdna
kdna validate dist/my_domain.kdna
kdna plan-load dist/my_domain.kdna

Quick Start

const {
  project: projectApi,
  cards: cardApi,
  compile,
  exportRuntime,
  distillation
} = require('@aikdna/kdna-studio-core');

// 1. Create a project
const project = projectApi.createProject('writing_judgment', 'domain', {
  author: { name: 'Writing Expert', id: 'writer_001' },
  judgmentCore: {
    highest_question: 'Which in-scope tradeoff should this asset resolve?',
    worldview: ['Observed task facts remain authoritative.'],
    value_order: ['prevent irreversible harm', 'preserve reversibility'],
    judgment_role: {
      acts_as: 'a scoped judgment authority',
      does_not_act_as: ['a fact source', 'a policy engine'],
      responsibility: 'Order qualitative tradeoffs inside the declared scope.'
    }
  }
});

// Optional: declare a distillation target before extracting from evidence.
const target = distillation.createDistillationTarget({
  domainName: 'writing_judgment',
  domainCategory: 'expression_writing',
  ownerScope: 'personal',
  granularity: 'core_principles',
  taskScope: 'longform article diagnosis and revision',
  includeAreas: ['argument structure', 'reader framing', 'evidence density'],
  excludeAreas: ['life habits', 'food preference']
});
project.distillation_target = target;

// 2. Create judgment cards
let card = cardApi.createCard('axiom', {
  one_sentence: 'Most writing problems are structural, not language-level.',
  full_statement: 'When reviewing content, diagnose structure before language.',
  why: 'Surface polishing on structurally weak content wastes effort.',
  applies_when: ['User asks to review content'],
  does_not_apply_when: ['User explicitly asks for grammar check only'],
  failure_risk: 'May over-diagnose structural problems in content that only needs polish.'
});

// 3. This example records optional review provenance for the card.
// Card state operations are immutable, so keep each returned card.
card = cardApi.transitionCard(card, 'revised', { by: 'writer_001' });
card = cardApi.lockCard(card, {
  by: 'writer_001',
  statement: 'This represents my professional writing judgment.',
  checked: { applies_when: true, does_not_apply_when: true, failure_risk: true }
});
project.cards.push(card);

// 4. Check readiness
const gate = projectApi.checkHumanLockGate(project); // optional review report

// 5. Compile and runtime-export. Human Lock does not grant creation permission.
const compiled = compile.compileDomain(project, { strictAuthority: false });
const runtimeAsset = exportRuntime.exportRuntimeAsset(project, { compiled });
console.log(Object.keys(runtimeAsset.files), gate.lockedJudgmentCards);

For a smaller source-integrity-first flow, use the additive facade:

const { authoring } = require('@aikdna/kdna-studio-core');

const project = authoring.createProject('@example/writing-judgment');
const card = authoring.addSourceJudgment(project, {
  sourceType: 'human',
  sourceLabel: 'Author interview, 2026-07-20',
  statement: 'Diagnose structural problems before editing individual sentences.',
  rationale: 'Sentence polishing cannot repair a missing argument or an incoherent sequence.',
  appliesWhen: ['Reviewing a long-form article'],
  doesNotApplyWhen: ['The request is limited to spelling'],
  failureRisk: 'The review may exceed the requested scope.'
});
authoring.reviewJudgment(project, card.id, {
  by: 'reviewer-01',
  statement: 'I checked the source, judgment, scope, boundary, and risk.'
});
authoring.confirmJudgment(project, card.id, {
  by: 'reviewer-01',
  statement: 'I confirm this judgment for the declared scope.'
});
const runtimeAsset = authoring.exportRuntimeAsset(project);

Runtime Export Contract

compile.compileDomain(project) is an authoring compile step. It returns source and evidence artifacts for review, audit, and reports. It is not itself the runtime distribution contract.

Use exportRuntime.exportRuntimeAsset(project) to produce a canonical KDNA runtime source directory payload:

const { exportRuntime } = require('@aikdna/kdna-studio-core');

const runtimeAsset = exportRuntime.exportRuntimeAsset(project);
// runtimeAsset.files contains only:
// - mimetype
// - kdna.json
// - payload.kdnab
// - checksums.json

The exported files are tested against @aikdna/kdna-core.validate. In the OPEN workspace they are also tested against the current aikdna/kdna LoadPlan implementation when available.

Runtime creator metadata is optional provenance. Studio Core preserves a declared creator name and ID, but omits the entire creator record when no non-empty creator name is available. It never invents an Unknown identity. The Studio project's editable author object remains independent of this runtime validity rule.

Access values are canonicalized for runtime export:

| Studio / legacy value | Runtime value | |---|---| | open | public | | protected | licensed | | runtime | remote |

Top-level source JSON entries such as KDNA_Core.json, KDNA_Patterns.json, and KDNA_CARD.json must not be present in runtime export output.

Card Types (current)

| Type | Compiles to | Description | |------|------------|-------------| | axiom | KDNA_Core.json | Core judgment principle | | ontology | KDNA_Core.json | Concept boundaries | | framework | KDNA_Core.json | Structured diagnostic approach | | stance | KDNA_Core.json | Domain position/perspective | | misunderstanding | KDNA_Patterns.json | Common wrong interpretation | | self_check | KDNA_Patterns.json | Yes/no verification question | | banned_term | KDNA_Patterns.json | Terms to avoid and replacements | | term | KDNA_Patterns.json | Standard term definitions | | boundary | KDNA_Core.json | In-scope and out-of-scope boundaries | | risk | KDNA_Core.json | Named risks and mitigations | | aesthetic | KDNA_Core.json | Domain aesthetic judgment | | scenario | KDNA_Scenarios.json | Situational judgment examples | | case | KDNA_Cases.json | Source-authored cases | | pattern | KDNA_Patterns.json | Reusable judgment patterns | | reasoning | KDNA_Reasoning.json | Source-authored reasoning chains | | evolution_stage | KDNA_Evolution.json | Source-authored evolution stages |

Card State Machine

draft → revised → locked → tested → published → deprecated

Rules:

• locked/tested/published are Studio project review states, not KDNA Core format-validity states.
• Studio release exports use reviewed cards as release evidence.
• A validated .kdna file can still be structurally valid without Human Lock; trust, authorship, signatures, and release evidence are separate layers.

Human Lock

Human Lock is optional provenance metadata. It records that a human reviewed specific judgment fields in a Studio project. It is useful for public, enterprise, or high-risk assets, but it is not a KDNA format-validity requirement and does not certify content quality.

lockCard(card, {
  by: 'expert_id',
  statement: 'I confirm this reflects my domain judgment.',
  checked: {
    applies_when: true,
    does_not_apply_when: true,
    failure_risk: true
  }
});

Human Lock signatures are defined in the format layer (Core verifies them when manifest.author.public_key_pem is present), but the current Studio pipeline does not attach signatures to exported assets and does not write a public key into the manifest. Runtime signature verification is therefore inert for Studio exports: unsigned assets are valid, and no signature claim should be made for them. Wiring signing end-to-end is planned post-Preview work.

License

Apache-2.0 — see LICENSE.

KDNA Studio Core is open source. Official KDNA Studio App, hosted collaboration, managed review workflows, and enterprise private distribution may be commercial services.

Related

• KDNA Core — Official format
• kdna-cli — CLI tools
• kdna-core-swift — Swift runtime for macOS/iOS
• aikdna.com — Website