ContextForge 1.0.5

ContextForge 1.0.5

Investigated 2026-07-28 against fork commit b1d4a1856cc7178b98368f1f4bb4892b33046303 and current upstream documentation. ADR-0008 owns adoption.

Native path

• Use ContextForge JWT authentication, team/RBAC, /tokens, Virtual Servers, MCP/A2A routing, audit, and token-usage telemetry. Agent traffic must use a subject-scoped token; shared admin credentials remain outside the agent path.
• Use DATABASE_URL=postgresql+psycopg://... for production. Plain postgresql:// selects unavailable psycopg2. Alembic remains ContextForge’s native schema upgrade mechanism.
• Build the pinned source once on the Kubernetes BuildKit plane, publish SBOM and provenance, and deploy only image@sha256. Runtime uvx is transition debt, not a production release mechanism.

Migration trap

The upstream backup guide documents SQLite file copy and PostgreSQL pg_dump/pg_restore; it does not provide a cross-engine data copier. Configuration export/import covers catalog configuration, not the complete user, security-event, audit, and metrics database. Preserve the full SQLite authority by:

1. quiescing ContextForge and taking a retained Longhorn VolumeSnapshot;
2. running pinned pgloader with --on-error-stop into the empty CNPG database;
3. comparing every source and target table row count;
4. starting the prebuilt image against CNPG and proving native health, catalog, subject auth, telemetry, and rollback before retiring the PVC.

Registration trap

The 1.0.5 catalog documentation says catalog entries register at startup, but the pinned source exposes registration only through explicit catalog API calls. Its catalog schema also cannot express FractalOps passthrough headers, direct_proxy, secret-backed upstream bearer auth, or Virtual Server tool associations. The upstream Helm chart uses post-install/post-upgrade registration Jobs for the same gap.

Use one Argo PostSync Job, not a recurring CronJob. It reconciles the seven required gateways and Virtual Servers once per Armory rollout, fails the sync if any required registration fails, and leaves runtime refresh/health recovery to ContextForge. Delete this adapter when a stable native manifest/import path supports those four fields plus Kubernetes secret references.

Upgrade triggers

The six-hour stable channel follows official stable releases only after identity fixes #5426, #5671, and #5947 are included. Each advance rebuilds through Kubernetes BuildKit and promotes one digest.

Authoritative references: configuration, security, catalog, Helm deployment, backup, upgrade, and pgloader SQLite migration.