Release Map
Repository Release Surfaces
Section titled “Repository Release Surfaces”release.config.json product.version is authoritative. The current source state is 1.0.0-rc.3; successive release candidates increment -rc.N.
| Surface | Current source |
|---|---|
| Root package manager | package.json declares pnpm@11.1.1. |
| Release scripts | scripts/release.sh, scripts/release.mjs, release.config.json. |
| Docker runtime compose | infra/docker/runtime-compose.yml. |
| Helm chart | infra/helm/caracal/Chart.yaml and values files. |
| Docs build | docs/package.json. |
Service Images
Section titled “Service Images”Caracal shares built images across roles, but each role remains a separate process or pod.
| Image name | Roles | Runtime |
|---|---|---|
caracal-node | API, Coordinator | Node |
caracal-go | STS, Gateway, Audit | Go |
caracal-web | Web console, auth BFF | Node |
caracal-postgres | Postgres, migrations | - |
caracal-redis | Redis, stream provisioning | - |
caracal-runtime | Runtime distribution | Node/Bun |
Role selection:
caracal-node→command: ["/app/api/dist/main.js"]or["/app/coordinator/dist/main.js"].caracal-go→command: ["/usr/local/bin/sts"],["/usr/local/bin/gateway"], or["/usr/local/bin/audit"].
Runtime Compose references ${CARACAL_REGISTRY:-ghcr.io/garudex-labs/}<image>:v${CARACAL_VERSION}.
Published Package Names
Section titled “Published Package Names”| Area | TypeScript | Python | Go |
|---|---|---|---|
| SDK | @caracalai/sdk | caracalai-sdk | github.com/garudex-labs/caracal/packages/sdk/go |
| Admin | @caracalai/admin | caracalai-admin | github.com/garudex-labs/caracal/packages/admin/go |
| Core | @caracalai/core | caracalai-core | github.com/garudex-labs/caracal/packages/core/go |
| Identity | @caracalai/identity | caracalai-identity | github.com/garudex-labs/caracal/packages/identity/go |
| OAuth | @caracalai/oauth | caracalai-oauth | github.com/garudex-labs/caracal/packages/oauth/go |
| Revocation | @caracalai/revocation | caracalai-revocation | github.com/garudex-labs/caracal/packages/revocation/go |
| Verify engine | @caracalai/verify | caracalai-verify | github.com/garudex-labs/caracal/packages/verify/go |
Versioning Notes
Section titled “Versioning Notes”- One product release stamps every package, image, binary, chart, and generated release record with the same SemVer.
- Every nested Go module uses
<module-directory>/vX.Y.Z[-rc.N]at the same commit as the root product tag. - Pin exact image tags in production values.
- Run migration and readiness validation after image or chart changes.
- Do not use product-management runtime CLI aliases as release surfaces; broad automation belongs to the Admin API and zone-scoped dispatch belongs to the Control API.
Documentation Mapping
Section titled “Documentation Mapping”- Before stable
v0.2.0, unversioned source is served at/v0.2/; nov0.2snapshot directory exists. - Stable
v0.2.0creates the writablev0.2snapshot. v0.2.xpatches update that same current minor after release; they never create patch-specific documentation trees.- A later stable minor archives unversioned source as the new current snapshot, exposes ongoing work at
/next/, and locks the superseded minor with its SHA-256 digest.
Next Step
Section titled “Next Step”Use Wire Contracts when validating SDK, adapter, exporter, or connector compatibility.