Skip to main content

Arcan Engineering Constitution

This document defines the architecture, standards, and contracts for the Arcan ecosystem. Every contributor — human or AI — must follow these rules. No exceptions without explicit approval. This is the single source of truth. If code contradicts this document, the code is wrong.

What This Constitution Covers​

The Arcan Engineering Constitution is the authoritative reference for how Arcan is designed, built, and operated. It spans product identity, architecture, data layer design, security contracts, and coding standards.

Foundations​

  • Product Identity — What Arcan is, what ships in the core binary, deployment modes, plugin tiers, and the plugin execution model.
  • Architecture Overview — Repo structure, dependency direction, forbidden dependencies, interface ownership, and narrow interface patterns.
  • Schema Migrations — Embedded numbered migration strategy for SQLite and PostgreSQL.
  • Plugin Data Isolation — How the core owns all data and plugins remain stateless compute.
  • Schema Conventions — Naming rules, soft delete vs hard delete, and timestamp format standards.
  • Multi-Tenancy — Tenant isolation via realm ownership, store layer enforcement, and the future org_id migration path.

Security​

  • Threat Model — Attack surfaces, threats, and mitigations across all system components.
  • Plugin Capabilities — Capability enum, grant rules by plugin tier, and the security property that plugins have no direct I/O access.
  • Key Hierarchy — Master key, HKDF-derived keys, and registry signing keys.
  • Secret Zero — Bootstrap trust chain, auto-generated master key, and the rule that Arcan stores references only.