janus-sdk

Repository: https://git.sovereign-society.org/janus/janus-sdk Version: 0.1.0-DRAFT Status: DRAFT — Initial Architecture Authority: Markus Maiwald + Voxis Forge

---

Overview

janus-sdk is the stable Application Binary Interface (ABI) for calling Janus code from foreign languages. It is NOT a library that embeds into foreign binaries. It is a host interface that foreign code calls INTO.

┌─────────────────────────────────────────────────────────────┐
│                    FOREIGN HOST PROCESS                       │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
│  │ janus-sdk- │    │ janus-sdk- │    │ janus-sdk- │   │
│  │    c       │    │   wasm     │    │   rust     │   │
│  │  (ref)    │    │ (first cls)│    │ (comm exp)│   │
│  └──────┬─────┘    └──────┬─────┘    └──────┬─────┘   │
└─────────┼─────────────────┼─────────────────┼──────────┘
           │                 │                 │
           └─────────────────┼─────────────────┘
                             │ C ABI (janus_sdk.h)
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                     JANUS RUNTIME                            │
│  Grains, Actors, Business Logic                            │
└─────────────────────────────────────────────────────────────┘

---

Repository Structure

janus-sdk/
├── janus_sdk.h              # Root sovereign index (FROZEN ABI)
├── CLAUDE.md                # AI context
├── README.md               # This file
├── LICENSE
│
├── ref/                    # Reference Implementations
│   ├── c/                  # C REFERENCE (PRIMARY)
│   │   ├── janus_sdk_ref.c
│   │   └── Makefile
│   └── wasm/               # WASM FIRST-CLASS
│       ├── janus_sdk_wasm.zig
│       └── janus_sdk_wasm.js
│
├── sdk/                    # Feature: Core SDK (internal)
│   ├── sdk.zig
│   ├── hooks.zig
│   └── errors.zig
│
├── caps/                   # Feature: Capabilities
│   └── caps.zig
│
└── types/                  # Feature: Types
    └── types.zig

---

Classification: Official vs Community

Component	Status	Owner	Purpose
janus_sdk.h	OFFICIAL	Janus team	Frozen ABI, versioned
ref/c/	OFFICIAL	Janus team	Primary reference implementation
ref/wasm/	OFFICIAL	Janus team	First-class WASM support
janus-sdk-go/	COMMUNITY EXPERIMENT	Community	Go adapter (fork this)
janus-sdk-rust/	COMMUNITY EXPERIMENT	Community	Rust adapter (fork this)

---

Reference Implementations

C (Primary Reference)

THE reference implementation. Direct mapping to janus_sdk.h. Zero overhead.

#include "janus_sdk.h"

int main() {
    JanusContext* ctx;
    janus_init(&ctx, &(JanusCapToken){0, JANUS_CAP_INVOKE}, JANUS_SDK_VERSION_1_0_0);
    
    janus_invoke(ctx, "myapp", "handle_order", NULL, 0);
    
    janus_shutdown(ctx);
}

Build: make -C ref/c

WASM (First-Class)

Janus in browsers, WASM-native environments, fast plugin systems.

const janus = await JanusWASM.load('./janus_sdk_wasm.wasm');
const ctx = janus.open(JanusWASM.CAP_INVOKE);
await janus.invoke(ctx, 'myapp', 'handle_order', order);

Build: zig build-obj -target wasm32-wasi ref/wasm/janus_sdk_wasm.zig

---

Community Experiments

These are NOT officially maintained. Fork and adapt for your needs.

janus-sdk-go

Go adapter — reference for Go developers.

ctx, _ := janus.Open(janus.CapInvoke)
ctx.Invoke("myapp", "handle_order", order)

Repository: Community-maintained

janus-sdk-rust

Rust adapter — for Rust developers who want Janus integration.

let ctx = JanusContext::new(CAP_INVOKE)?;
ctx.invoke("myapp", "handle_order")?;

Repository: Community-maintained

---

Capability Gating

All foreign calls pass through capability guard:

Capability	Bit	Purpose
invoke	0x01	Call any Janus function
spawn	0x02	Create new grains
alloc	0x04	Direct memory allocation
log	0x08	Write to Janus logger
query	0x10	Read grain state

---

ABI Versioning

SDK Version	Janus Version	Status
1.0.0	0.3.x	Planned
1.1.0	0.4.x	Planned

Symbol versioning via ELF annotations.

---

Panopticum Compliance

• Feature-orthogonal layout (ref/c, ref/wasm, sdk, caps, types)
• Root sovereign index (janus_sdk.h)
• Tests colocated
• Max depth = 3
• README.md present per feature

---

References

• Janus Grafting Doctrine (janus-lang/.claude/rules/grafting.md)
• Capability Gating Doctrine (janus-lang/.claude/rules/capability-gating.md)

Note: Specifications are in .agents/specs/ (internal only, not distributed)

---

Developed with Voxis Forge assistance