ONYX IFEM

ONYX is an interface-first execution framework. This repository turns the IFEM v2.0 contract baseline into an executable, independently testable system.

The executable product includes all 18 ONYX IFEM bounded contexts and all 294 v2.0 command/event artifacts. It enforces authority, optimistic concurrency, idempotency, organization boundaries, durable state/event/outbox persistence, complete HTTP/OpenAPI access, and graphical command controls.

Repository layout

contracts/v2.0/       Versioned machine-readable contract baseline
codegen/rust/          Rust command/event types and canonical envelopes
codegen/typescript/    TypeScript command/event types and canonical envelopes
validation/            Executable Python contract fixtures and validation evidence
src/api/              Service composition and port-free request dispatcher
src/auth/             Ed25519 bearer authentication and JWT validation
src/contracts/        Canonical envelope and shared runtime types
src/infrastructure/   SQLite persistence and transactional outbox delivery
src/organization/     Organization hierarchy domain and application service
src/identity-authority/ User, role, device, and delegation authority service
src/context-link/     Validated cross-domain relationship service
src/meeting/          Participant, decision, and action meeting lifecycle
src/conversation/     Member-bound communication and redaction lifecycle
src/mission/          Mission domain and application service
src/work/             Work/Task domain and application service
src/timeline/         Timeline domain and application service
src/reporting-evidence/ Report domain and application service
src/shared/           Deterministic serialization and identifier utilities
tests/                Contract and domain verification
tools/                Repository-level validation commands
web/                  Next.js operations command center

Requirements

• Node.js 24 or newer
• Rust stable (for the supplied Rust SDK)
• Python 3.13 with validation/requirements.txt (for the supplied fixture validator)

The API has no third-party runtime dependencies. TypeScript and the matching Node.js type definitions are development-only dependencies.

Verify

npm ci
npm run check

The check pipeline validates the imported contracts, performs a strict no-emit TypeScript compilation, and runs the complete test suite, including a black-box real-socket process and graceful-shutdown test. See Type safety.

Validate every language artifact restored from the original package:

python3 -m venv .venv
.venv/bin/python -m pip install -r validation/requirements.txt
npm run check:artifacts

check:artifacts reconciles the complete 372-file upstream inventory, checks both SDKs against all 144 commands and 150 events, type-checks TypeScript, executes the Python fixtures, and builds/tests Rust with its committed lockfile.

Run the API

npm start

The server listens on 127.0.0.1:3000 by default. Configure ONYX_HOST, ONYX_PORT, and replica identifiers when needed.

Authentication is disabled for local development. Production deployments can require Ed25519-signed bearer tokens with ONYX_AUTH_MODE=required; single-PEM and static-JWKS key rotation profiles are documented in Authentication and authorization.

Every response carries an x-request-id; the server emits redaction-safe structured JSON logs. Use /healthz for liveness and /readyz for persistence plus messaging readiness. See Observability.

Prometheus-compatible, bounded-cardinality operational metrics are available at GET /metrics; keep this infrastructure endpoint off public ingress routes. Provisionable alert rules, a Grafana dashboard, and response procedures are in Production monitoring.

Finite token-bucket, concurrency, header, receive, socket, and connection-reuse limits protect the HTTP boundary. See HTTP resilience and overload protection.

Set ONYX_OUTBOX_WEBHOOK_URL to run the crash-recoverable outbox publisher. Production configuration, HTTPS delivery headers, lease sizing, and graceful shutdown behavior are documented in Production deployment.

The hardened production container, CI security gates, CycloneDX SBOM, multi-platform GHCR publishing, and tag-based release process are documented in Container and release supply chain.

The hardened singleton StatefulSet, persistent-volume model, probes, secrets, network policy, and immutable-image deployment procedure are documented in Kubernetes deployment.

Online backup, manifest verification, restore rehearsal, and migration compatibility checks are available through the db:backup, db:verify, and db:restore scripts. See Backup and disaster recovery.

The application dispatcher is independent of the Node HTTP transport, so route workflows can run without opening sockets. See HTTP application architecture.

A self-contained OpenAPI 3.1.2 document is available at GET /openapi.json or through npm run openapi. See OpenAPI description.

State is in-memory unless ONYX_DB_PATH is set. Enable durable SQLite persistence with:

ONYX_DB_PATH=./data/onyx.db npm start

Run the web command center

Start the complete local product with one command after installing both package sets:

npm ci
npm ci --prefix web
npm run dev:stack

Open http://localhost:3002. The launcher starts the durable API on port 3001, the graphical command center on port 3002, waits for both readiness checks, and stops both processes together on Ctrl+C. Override the defaults with ONYX_PORT, ONYX_WEB_PORT, and ONYX_DB_PATH.

To run each process separately, run the API on port 3001, then start the graphical command center in a second terminal:

ONYX_HOST=127.0.0.1 ONYX_PORT=3001 ONYX_DB_PATH=./data/onyx.db npm start

cd web
npm ci
npm run dev -- --port 3002

Open http://localhost:3002. The web server proxies requests to http://127.0.0.1:3001 by default. Set ONYX_API_URL to use another API origin. The command center provides organization hierarchy, identity-authority, context-graph, meeting, and conversation controls plus mission, task, timeline, and report creation, with mission lifecycle actions, immutable event history, cursor-based collection pagination, and shareable record URLs with browser Back/Forward restoration.

Verify the web application independently with:

cd web
npm test

Organization, Identity/Authority, Context Link, Meeting, Conversation, Mission, Work, Timeline, and Reporting-Evidence keep separate context ownership while sharing the same transactional database. See Persistence.

Every durable event is written to a transactional outbox in the same commit as its aggregate state. The bounded dispatcher supports exclusive leases, retry backoff, dead-lettering, and at-least-once delivery with stable event identifiers. A persistent consumer inbox adds per-consumer deduplication, tamper detection, and crash-recoverable processing leases.

Available endpoints:

• GET /healthz
• GET /readyz
• GET /metrics
• GET /openapi.json
• POST /v1/organization/commands/{CommandType}
• GET /v1/organizations?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/organizations/{id}?organization_id={id}
• GET /v1/organizations/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/identity-authority/commands/{CommandType}
• GET /v1/users?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/users/{id}?organization_id={id}
• GET /v1/users/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/context/commands/{CommandType}
• GET /v1/context-links?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/context-links/{id}?organization_id={id}
• GET /v1/context-links/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/meeting/commands/{CommandType}
• GET /v1/meetings?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/meetings/{id}?organization_id={id}
• GET /v1/meetings/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/communication/commands/{CommandType}
• GET /v1/conversations?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/conversations/{id}?organization_id={id}
• GET /v1/conversations/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/file/commands/{CommandType}
• GET /v1/files?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/files/{id}?organization_id={id}
• GET /v1/files/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/approval/commands/{CommandType}
• GET /v1/approvals?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/approvals/{id}?organization_id={id}
• GET /v1/approvals/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/capacity/commands/{CommandType}
• GET /v1/capacity-profiles?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/capacity-profiles/{id}?organization_id={id}
• GET /v1/capacity-profiles/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/forecasting/commands/{CommandType}
• GET /v1/forecasts?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/forecasts/{id}?organization_id={id}
• GET /v1/forecasts/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/automation/commands/{CommandType}
• GET /v1/automation-rules?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/automation-rules/{id}?organization_id={id}
• GET /v1/automation-rules/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/notification/commands/{CommandType}
• GET /v1/notifications?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/notifications/{id}?organization_id={id}
• GET /v1/notifications/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/synchronization/commands/{CommandType}
• GET /v1/synchronizations?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/synchronizations/{id}?organization_id={id}
• GET /v1/synchronizations/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/audit/commands/{CommandType}
• GET /v1/audit-partitions?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/audit-partitions/{id}?organization_id={id}
• GET /v1/audit-partitions/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/policy/commands/{CommandType}
• GET /v1/policies?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/policies/{id}?organization_id={id}
• GET /v1/policies/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/mission/commands/{CommandType}
• GET /v1/missions?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/missions/{id}?organization_id={id}
• GET /v1/missions/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/work/commands/CreateTask
• GET /v1/tasks?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/tasks/{id}?organization_id={id}
• GET /v1/tasks/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/timeline/commands/CreateTimeline
• GET /v1/timelines?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/timelines/{id}?organization_id={id}
• GET /v1/timelines/{id}/history?organization_id={id}&after_version=0&limit=100
• POST /v1/reporting-evidence/commands/CreateReport
• GET /v1/reports?organization_id={id}&limit=100&cursor={opaque}
• GET /v1/reports/{id}?organization_id={id}
• GET /v1/reports/{id}/history?organization_id={id}&after_version=0&limit=100

Implemented command types:

• CreateMission
• CreateBlueprintRevision
• SubmitBlueprint
• ActivateMission
• PauseMission
• ResumeMission
• OperationalHaltMission
• RestartMission
• CloseMission
• CancelMission
• ArchiveMission

See Mission context for lifecycle and authority details.

All command handlers share strict validation of the canonical v2.0 envelope before domain-specific payload checks. Emitted events are validated and their canonical integrity digests are verified before persistence. See Runtime contract validation.

The Work context implements the complete Task lifecycle plus owner, priority, and dependency mutations. A task may be created only when its referenced Mission exists inside the same organization boundary. See Work context.

The Timeline context implements creation, deadlines, milestones, critical markers, penalty zones, schedule-exception resolution, and archival. A timeline may target an existing Mission or Task inside the same organization boundary. See Timeline context.

The Reporting-Evidence context implements report creation, evidence verification/rejection, review approval/rejection, resubmission, and archival. Reports may target an existing Mission, Task, or Timeline. See Reporting-Evidence context.

The Organization context owns the tenant hierarchy: workspaces, departments, teams, and groups. It supports team moves, safe department archival, and lifecycle-fenced organization archival. See Organization context.

The Identity/Authority context owns users, role assignments, registered devices, and scoped delegations. Role, device, delegation, and user-state revocation advance authority epochs so stale clients fail closed. See Identity and authority context.

The Context Link context owns validated cross-domain edges between existing objects. It supports exact metadata replacement, strength changes, archival, and restore-time endpoint revalidation. See Context Link context.

The Meeting context owns scheduled and in-progress sessions, organization-bound participants, immutable decisions, proposed action items, and terminal outcomes. See Meeting context.

The Conversation context owns topic-linked member rooms, messages, edits, reactions, privacy-safe redaction, and archival. See Conversation context.

The File context owns checksum-bound chunked uploads, immutable versions, access grants, quarantine, and archival. See File context.

The Approval context owns reviewer assignment, threshold decisions, delegation, escalation, cancellation, reversal, and reopening. See Approval context.

The Capacity context owns resource availability, workload allocations, deterministic balances, snapshots, recalculation, and archival. See Capacity context.

The Forecast context owns horizon-bound baselines, probability-weighted scenarios, recalculation, publication, and archival. See Forecast context.

The Automation context owns enablement-fenced rules, trigger evaluations, action receipts, retries, compensation, and archival. See Automation context.

The Notification context owns recipient resolution, multi-channel delivery batches, retry failures, escalation, acknowledgement, and archival. See Notification context.

The Synchronization context owns operation-batch exchange, vector-clock convergence, conflict detection, resolution, escalation, replica acknowledgement, and closure. See Synchronization context.

The Audit context owns hash-chained entries, sealed partitions, bounded exports, integrity verification, and archival. See Audit context.

The Policy context owns versioned decisions, violations, legal holds, quota thresholds, and rate-limit enforcement. See Policy context.

The HTTP adapter exposes every command across all 18 executable bounded contexts; no bounded context remains contract-only.

Contract maturity

The imported v2.0 package contains 294 command/event schemas. All 294 artifacts are FIELD_COMPLETE, and all 144 commands have executable handlers, persistence, HTTP/OpenAPI routes, and graphical controls.

The Mission context is now lifecycle-complete, including operational halt, restart with lifecycle-epoch fencing, close, and archive transitions.

All 18 bounded contexts are lifecycle-complete: Organization, Identity/Authority, Context Link, Meeting, Conversation, File, Approval, Capacity, Forecast, Automation, Notification, Synchronization, Audit, Policy, Mission, Work, Timeline, and Reporting-Evidence.