Hinge Package Manager

Hinge Package Manager Architecture

Status: Active (Phase A-H implemented) Audience: Compiler contributors, package authors, federation operators, AI assistants Purpose: Define the sovereign supply chain architecture for Janus packages

Overview

Hinge is Janus’s sovereign package manager — 18K lines of Zig, 25 modules, ~265 tests. It implements a cryptographically verifiable, federated supply chain where trust is computed, not assumed.

Key Properties:

Zero external dependencies: Every module imports only const std = @import("std")
Standalone reusability: Any module can be extracted and used independently (e.g., by the Libertaria SDK)
Location: tools/hinge/ in the Janus repository
Principle: The Garden Wall doctrine — “only proven code survives publication”

janus init mylib        # Create project with janus.kdl manifest
janus build src/main.jan main  # Compile
janus pkg pack          # Normalize + archive into .jpk
janus pkg seal          # Ed25519 sign the archive
janus pkg publish       # DMP gossip announcement + transparency log entry

System Architecture

+-----------------------------------------------------------------------+
|                         JANUS CLI (main.zig)                          |
|    init | build | pkg pack | pkg seal | pkg publish | pkg resolve     |
+-----------------------------------------------------------------------+
         |              |              |              |
         v              v              v              v
+----------------+ +----------------+ +----------------+ +----------------+
|  FOUNDATION    | |  PACKING       | |  IDENTITY &    | |  QUALITY       |
|  (Phase A)     | |  (Phase B)     | |  TRUST (C)     | |  (Phase D)     |
|                | |                | |                | |                |
| semver         | | packer         | | crypto_sign    | | proof_cert     |
| resolver       | | sbom           | | identity       | | quality_gate   |
| lockfile       | | cid_verify     | | trust_policy   | |                |
+----------------+ +----------------+ +----------------+ +----------------+
         |              |              |              |
         v              v              v              v
+----------------+ +----------------+ +----------------------------------+
|  TRANSPARENCY  | |  FEDERATION    | |  POST-QUANTUM & POLICY (G)       |
|  (Phase E)     | |  (Phase F)     | |                                  |
|                | |                | |  crypto_dilithium                 |
| transparency   | | chapter        | |  profile_enforce                  |
|   _log         | | witness        | |  org_policy                       |
| revocation     | | trust_graph    | +----------------------------------+
|                | | reputation     |
|                | | dmp_announce   | +----------------------------------+
|                | | registry       | |  PERFORMANCE & OBSERVABILITY (H)  |
+----------------+ +----------------+ |                                  |
                                      |  fetch_pool  | resolution_cache  |
                                      |  ci_mode     | json_output       |
                                      |  cache_mgr   | dep_graph         |
                                      |  audit       |                   |
                                      +----------------------------------+

Module Map

Phase A — Foundation

Core dependency management primitives. These modules form the backbone of every janus build and janus pkg resolve operation.

Module	File	Tests	Purpose
semver	`semver.zig`	~30	Semantic versioning: parse, compare, range matching (`>=1.2.0 <2.0.0`)
resolver	`resolver.zig`	~25	Dependency resolution with backtracking and conflict reporting
lockfile	`lockfile.zig`	~15	Deterministic lockfile generation and parsing (`janus.lock`)
main	`main.zig`	—	CLI command dispatch and argument parsing

Resolution Algorithm:

                  ┌──────────────────────┐
                  │   janus.kdl manifest │
                  └──────────┬───────────┘
                             │ parse deps
                             v
                  ┌──────────────────────┐
                  │   Version Ranges     │
                  │   foo >= 1.2 < 2.0   │
                  │   bar ^3.1.0         │
                  └──────────┬───────────┘
                             │ query registry
                             v
                  ┌──────────────────────┐
                  │   Candidate Sets     │──┐
                  │   foo: [1.2.0, 1.3.1]│  │ backtrack
                  │   bar: [3.1.0, 3.2.0]│  │ on conflict
                  └──────────┬───────────┘<─┘
                             │ solve
                             v
                  ┌──────────────────────┐
                  │   janus.lock         │
                  │   (pinned versions)  │
                  └──────────────────────┘

Phase B — Packing

Content normalization and archive creation. Transforms a project directory into a reproducible, content-addressed .jpk archive.

Module	File	Tests	Purpose
packer	`packer.zig`	~20	Content normalization, `.jpk` archive creation
sbom	`sbom.zig`	~10	Software Bill of Materials generation (dependency tree snapshot)
cid_verify	`cid_verify.zig`	~15	BLAKE3 content-addressed identity verification

Content Identity (CID) Format:

blake3:a7f3b2c1d4e5f6789012345678901234567890123456789012345678901234ab
       └─────────────── 64-char hex of BLAKE3 hash ───────────────────┘

The packer normalizes file order, strips timestamps, and produces a deterministic archive. Two identical source trees always produce the same CID, regardless of filesystem metadata.

Phase C — Identity and Trust

Cryptographic identity management and trust policy enforcement. Every package author has a sovereign identity; every operation is signed.

Module	File	Tests	Purpose
crypto_sign	`crypto_sign.zig`	~20	Ed25519 signing and signature verification
identity	`identity.zig`	~15	DID:sovereign generation and management
trust_policy	`trust_policy.zig`	~12	Trust graph configuration and policy enforcement

DID Format:

did:sovereign:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
              │└─────────────── base58btc(ed25519_pubkey) ──┘
              └── multibase prefix: 'z' = base58btc

Signing Flow:

// 1. Generate identity
const keypair = try identity.generate();
// DID: did:sovereign:z<base58btc(keypair.public_key)>

// 2. Sign package archive
const signature = try crypto_sign.sign(archive_bytes, keypair.secret_key);

// 3. Verify on consumer side
const valid = try crypto_sign.verify(archive_bytes, signature, author_public_key);

Phase D — Quality

Proof certificates and quality gates. Packages carry embedded evidence that they were tested and meet configurable quality thresholds.

Module	File	Tests	Purpose
proof_cert	`proof_cert.zig`	~12	Proof certificates: test results embedded in packages
quality_gate	`quality_gate.zig`	~10	Configurable quality gates (coverage, lint, etc.)

The Capsule Standard:

Every publishable package (Capsule) contains three indivisible elements:

The Source — Logic (structs, functions, modules)
The Proof — Test results + Proof Certificate generated by the compiler
The Contract — Capability Manifest (what it touches: FS, Net, etc.)

hinge rejects any publish attempt without a valid Proof Certificate. This is enforced at the protocol level, not by convention.

Phase E — Transparency

Append-only transparency log and revocation infrastructure. Every publication creates a Merkle tree entry; every revocation is cryptographically signed.

Module	File	Tests	Purpose
transparency_log	`transparency_log.zig`	~18	BLAKE3 Merkle tree, DID-signed checkpoints
revocation	`revocation.zig`	~10	Revocation certificates (advisory + critical severity)

Merkle Tree Structure:

                    ┌──────────┐
                    │ Root CID │  ← DID-signed checkpoint
                    └────┬─────┘
                   ┌─────┴─────┐
                   │           │
              ┌────┴────┐ ┌───┴─────┐
              │ H(A|B)  │ │ H(C|D)  │
              └────┬────┘ └────┬────┘
             ┌─────┴──┐  ┌────┴──┐
             │        │  │       │
           ┌─┴─┐  ┌──┴┐ ┌┴──┐ ┌─┴─┐
           │ A │  │ B │ │ C │ │ D │  ← Package publication entries
           └───┘  └───┘ └───┘ └───┘

Each leaf contains: package name, version, CID, author DID, timestamp, and signature. Checkpoints are signed by the registry operator’s DID, enabling third-party audit of the entire publication history.

Revocation Severities:

advisory — Soft warning, consumer decides whether to continue
critical — Hard block, package cannot be resolved until replacement is published

Phase F — Federation

The core of Hinge’s decentralized governance model. No single entity controls the registry. Trust is computed from a graph of cryptographic attestations.

Module	File	Tests	Purpose
chapter	`chapter.zig`	~15	Chapter formation, N-of-M governance, charter signing
witness	`witness.zig`	~12	Cross-Chapter attestation, consensus evaluation
trust_graph	`trust_graph.zig`	~14	BFS trust distance computation, path reconstruction
reputation	`reputation.zig`	~12	Weighted reputation formula, catastrophic drop detection
dmp_announce	`dmp_announce.zig`	~10	DMP gossip topic namespace, announcement serialization
registry	`registry.zig`	~15	Federated registry queries, result merging, deduplication

Federation Model:

┌─────────────────────────────────────────────────────────┐
│                    FEDERATION LAYER                      │
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ Chapter  │<──>│ Chapter  │<──>│ Chapter  │          │
│  │ "Core"   │    │ "Crypto" │    │ "WebDev" │          │
│  │ 5 members│    │ 3 members│    │ 4 members│          │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘          │
│       │               │               │                 │
│       │    Witness     │    Witness    │                 │
│       │  Attestations  │  Attestations │                 │
│       │               │               │                 │
│  ┌────v───────────────v───────────────v─────┐           │
│  │           TRUST GRAPH (BFS)              │           │
│  │  max_distance: 3 hops                    │           │
│  │  reputation threshold: 0.4               │           │
│  └────────────────────┬─────────────────────┘           │
│                       │                                  │
│  ┌────────────────────v─────────────────────┐           │
│  │         DMP GOSSIP TRANSPORT             │           │
│  │  topics: hinge/announce/<name>/<ver>     │           │
│  │          hinge/revoke/<name>/<ver>       │           │
│  │          hinge/witness/<chapter>/<cid>   │           │
│  └──────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────┘

Chapter Governance:

A Chapter is a group of 3+ maintainers who form a shared trust unit:

Formation: Founding members sign a charter document with their DIDs
Charter: Defines Chapter DID, governance rules, and domain focus
Admission: N-of-M vote required to add new members (e.g., 3-of-5)
Removal: N-of-M vote required to remove members (higher threshold than admission)
Chapter DID: Derived from the charter hash, not from any single member

Witness Consensus:

When a package is published, Chapters can attest to its quality:

Package "crypto-utils@1.2.0" published by did:sovereign:zAlice
  │
  ├── Chapter "Core" attests ✓  (3/5 members reviewed)
  ├── Chapter "Crypto" attests ✓ (2/3 members reviewed)
  └── Chapter "WebDev" — no attestation

Consensus: K=2 attestations from N=2 distinct Chapters → VERIFIED

Trust Graph (BFS):

Trust distance is computed as the shortest path in the attestation graph:

// BFS from consumer's trusted root to package author
const path = try trust_graph.findShortestPath(
    consumer_did,    // starting node
    author_did,      // target node
    max_distance,    // default: 3 hops
);
// path: [consumer] -> [Chapter "Core"] -> [Chapter "Crypto"] -> [author]
// distance: 3 (within threshold)

Reputation Formula:

score = 0.4 * accuracy + 0.2 * frequency + 0.2 * cross_verify + 0.2 * tenure

Component	Weight	Description
`accuracy`	0.4	Ratio of attestations that proved correct over time
`frequency`	0.2	How regularly the entity participates in reviews
`cross_verify`	0.2	How often the entity’s attestations are confirmed by other Chapters
`tenure`	0.2	Length of active participation in the federation

Catastrophic Drop Detection: If an entity’s accuracy drops below a threshold within a time window (e.g., 3 false attestations in 30 days), the reputation score is immediately halved and a review is triggered.

Phase G — Post-Quantum and Policy

Forward-looking cryptographic migration and organizational policy enforcement.

Module	File	Tests	Purpose
crypto_dilithium	`crypto_dilithium.zig`	~12	Dilithium3 backend, Ed25519+Dilithium3 hybrid signatures
profile_enforce	`profile_enforce.zig`	~8	Profile capability ladder enforcement
org_policy	`org_policy.zig`	~8	Organization-level license and capability policies

Hybrid Signature Model:

┌─────────────────────────────────────────────┐
│              SIGNED PACKAGE                  │
│                                              │
│  archive_cid: blake3:a7f3b2...              │
│                                              │
│  signatures:                                 │
│    ├── ed25519: <64 bytes>     ← Classical  │
│    └── dilithium3: <2420 bytes> ← PQ-safe   │
│                                              │
│  Legacy clients verify Ed25519 alone.        │
│  PQ-aware clients verify both.               │
└─────────────────────────────────────────────┘

Dilithium3 is currently in simulation mode pending PQClean integration. The signature format is fixed; only the backend implementation will change when production-ready PQ libraries are available.

Profile Enforcement:

Packages declare their minimum profile requirement. The resolver rejects dependencies that exceed the consumer’s profile level:

:core package cannot depend on :service package
:service package cannot depend on :sovereign package

This enforces the capability ladder at the supply chain level, not just at compile time.

Phase H — Performance and Observability

Production-grade tooling for CI/CD pipelines, caching, visualization, and security auditing.

Module	File	Tests	Purpose
fetch_pool	`fetch_pool.zig`	~10	Concurrent package fetching with adaptive concurrency
resolution_cache	`resolution_cache.zig`	~8	LRU resolution cache, incremental resolution
ci_mode	`ci_mode.zig`	~6	CI/CD environment detection, strict defaults
json_output	`json_output.zig`	~8	Machine-readable JSON output for all commands
cache_mgr	`cache_mgr.zig`	~10	Content-addressed storage management, LRU pruning
dep_graph	`dep_graph.zig`	~8	Dependency graph visualization (text tree, DOT, JSON)
audit	`audit.zig`	~10	Security audit reports, license scanning, risk assessment

CI Mode Behavior:

When CI=true is detected (or --ci flag is passed):

Resolution uses lockfile only (no network queries)
All quality gates enforced at maximum strictness
JSON output enabled by default
Non-zero exit on any warning

Content-Addressed Cache:

~/.janus/cache/
├── objects/
│   ├── blake3/
│   │   ├── a7f3b2c1d4e5...  ← raw .jpk archive
│   │   ├── 9d4e8f2a3b1c...
│   │   └── ...
│   └── metadata/
│       ├── a7f3b2c1d4e5.json  ← package metadata
│       └── ...
├── resolution/
│   └── lru.db              ← resolution cache (LRU eviction)
└── trust/
    └── graph.db            ← cached trust graph state

Package Lifecycle

The complete journey of a package from creation to consumption:

AUTHOR SIDE                              CONSUMER SIDE
===========                              =============

1. janus init mylib
   └── Creates janus.kdl,
       src/main.jan, .gitignore

2. Write code, run tests
   └── janus test
       └── Generates Proof Certificate

3. janus pkg pack
   └── Normalize files
   └── Create .jpk archive
   └── Compute CID (blake3:<hex>)
   └── Embed SBOM + Proof Certificate

4. janus pkg seal                        5. janus pkg resolve
   └── Ed25519 sign archive                 └── Parse janus.kdl deps
   └── Dilithium3 sign (hybrid)             └── Query federated registry
   └── Attach signatures to .jpk            └── Check trust graph distance
                                             └── Verify reputation threshold
5. janus pkg publish                        └── Generate janus.lock
   └── DMP gossip announcement
   └── Transparency log entry            6. janus pkg fetch
   └── Registry index update                └── Download .jpk archives
                                             └── Verify CID integrity
6. Chapter witnesses review                  └── Verify Ed25519 signature
   └── Attest package quality                └── Check trust policy
   └── Cross-verify with other Chapters      └── Validate Proof Certificate
   └── Update reputation scores              └── Extract to cache

Cryptographic Architecture

Content Addressing

All package identity is derived from content, not from names or URLs:

Property	Value
Hash Function	BLAKE3
Format	`blake3:<64-char-hex>`
Input	Normalized archive bytes (deterministic order, no timestamps)
Collision Resistance	256-bit (equivalent to SHA-256)
Tree Hashing	Supported (enables parallel verification of large archives)
Length Extension	Immune (BLAKE3 is not Merkle-Damgard)

Digital Signatures

Scheme	Key Size	Signature Size	Purpose
Ed25519	32 bytes	64 bytes	Primary signing (classical)
Dilithium3	1952 bytes	2420 bytes	Post-quantum transition

Hybrid verification: Both signatures are attached to every package. Legacy clients that do not support Dilithium3 can verify Ed25519 alone and remain functional. PQ-aware clients verify both signatures and reject packages where either fails.

Transparency Log

The transparency log is a BLAKE3 Merkle tree with DID-signed checkpoints:

Leaf entries: BLAKE3(package_name || version || cid || author_did || timestamp)
Internal nodes: BLAKE3(left_child || right_child)
Checkpoints: Registry operator signs the root hash with their DID at regular intervals
Audit: Any third party can reconstruct the tree and verify checkpoint signatures

Design Decisions

KDL for Manifests, JSON for Wire Format

Following the Law of Representation: “KDL is for Intent (Humans). JSON is for State (Machines).”

janus.kdl — Human-editable manifest with comments, vague versions, readable structure
Wire protocol — Canonical JSON (RFC 8785) for registry queries, transparency log entries, and signatures

KDL lacks a canonicalization standard. A single extra space changes the hash. JSON has RFC 8785, ensuring deterministic serialization for cryptographic operations.

BLAKE3 over SHA-256

Performance: BLAKE3 is ~5x faster than SHA-256 on modern CPUs
Tree hashing: Native support for parallel hashing of large files
No length extension: BLAKE3 is immune to length extension attacks (unlike SHA-256)
Consistency: The Janus compiler already uses BLAKE3 for CID computation in the ASTDB

Ed25519 + Dilithium3 Hybrid

Ed25519: Small signatures (64 bytes), fast verification, universally supported
Dilithium3: NIST PQC Level 3, safe against quantum computers
Hybrid: Transition strategy — if either scheme is broken, the other provides fallback
Legacy support: Clients that only understand Ed25519 can still verify packages

Self-Contained Modules

Every Hinge module imports only const std = @import("std"). No cross-module dependencies beyond the standard library. This enables:

Libertaria SDK reuse: Any module can be extracted into a standalone library
Independent testing: Each module has its own test suite with zero setup
Auditing: Security review of a single module does not require understanding the entire system
Parallel development: Modules can be developed and released independently

No Centralized Registry

Hinge uses federated gossip via DMP topic namespaces instead of a central registry:

hinge/announce/<name>/<version> — Package publication announcements
hinge/revoke/<name>/<version> — Revocation notices
hinge/witness/<chapter>/<cid> — Chapter attestation messages

Any node running DMP can participate in the registry. There is no single point of failure, no single entity that can censor packages, and no corporate gatekeeper.

Reputation over Authority

Trust is mathematical, not political:

No curated “official” packages — Reputation scores are computed from verifiable attestation history
No “admin” accounts — Chapter governance is N-of-M voting, not single-operator fiat
Transparent scoring — The reputation formula is public; anyone can verify any entity’s score
Catastrophic accountability — False attestations immediately damage reputation

Memory Management

All Hinge modules follow the Janus allocator discipline:

pub fn init(allocator: std.mem.Allocator) HingeModule {
    return .{
        .allocator = allocator,
        // ...
    };
}

pub fn deinit(self: *HingeModule) void {
    // Release all owned resources
    self.entries.deinit(self.allocator);
}

Rules:

All allocations use the caller-provided allocator
defer module.deinit() immediately after init()
No global state, no ambient allocators
Test allocator detects leaks in every test

Files Reference

Path	Purpose
`tools/hinge/`	All Hinge source code (25 modules)
`tools/hinge/build.zig`	Standalone build configuration
`std/encoding/json/`	Native SIMD JSON parser (174 tests, RFC 8785)
`compiler/libjanus/ledger/kdl_parser.zig`	KDL manifest parser
`std/bridge/dmp_core.zig`	DMP gossip broker (transport layer)
`std/bridge/crypto_bridge.zig`	BLAKE3, SHA-256, HMAC primitives