Skip to main content
Version: v0.9.0a2

Pre-v0.9.0a1 Upgrade Notes

3 min readFor operators with older checkoutsUpdated 2026-05-19

Who this is for

Operators with an older local checkout, a stale dependency pin, or a pre-reset deployment artifact who need to align with the v0.9.0a1 alpha reset. If you're installing fresh, skip this and read Installation instead.

v0.9.0a1 is the first build.

No v1.0 or v2.0 Stigmem release shipped publicly. Per ADR-001 and ADR-019, treat older v0.x, v1.x, and v2.0 labels in local branches, old docs, or unpublished artifacts as internal development checkpoints.

For source checkouts, the alignment path is still a git pull plus rebuild. The node applies migrations at startup; take a database backup first if your local data matters.

What changed in the alpha reset​

Multi-tenant isolation (migration 012)​

The storage schema includes tenant_id columns on write-bearing tables for compatibility with the extracted multi-tenant plugin.

Existing rows

Receive tenant_id = "default" automatically on upgrade.

Existing API keys

Continue to work in the "default" tenant.

Single-tenant deployments

Require zero configuration changes.

Default installs

Collapse tenant resolution to "default" unless the opt-in multi-tenant plugin is registered.

See Multi-Tenancy for the feature record and extracted plugin source package.

Billing hooks​

A new stigmem_node.billing module emits a BillingEvent after every fact write and garden creation. The default implementation logs structured JSON to stderr — no configuration needed unless you want a custom backend. See Billing Hooks.

Source attestation​

Source attestation remains experimental in the v0.9.0aN line (Spec-X6-Source-Attestation). Default installs keep source-attestation behavior off; runtime enforcement lives behind stigmem-plugin-source-attestation registration and explicit plugin configuration. The current alpha plugin validates source claims and related recall/federation guards, but it does not prove release artifact provenance or mark accepted facts as locally re-attested. See Source Attestation.

Conformance test suite​

The source tree includes conformance and adversarial suites that drive the current alpha/beta readiness gates.

Pre-GA contract.

The public compatibility contract remains pre-GA. Pin exact versions and do not assume wire-format stability until the roadmap reaches v1.0.0.

Upgrade procedure​

git pull
docker compose up --build -d

The node runs apply_migrations() on startup. Migration 012_multi_tenant is idempotent; if it has already run in an older local checkout, it is skipped.

Verify the node is healthy and the migration applied:

curl -s http://localhost:8765/healthz
# → {"status": "ok"}

sqlite3 data/stigmem.db "SELECT version FROM schema_migrations ORDER BY version;"
# Should include: 012_multi_tenant

Without Docker (development install)​

git pull
uv sync          # or: pip install -e .
python -m stigmem_node

Persistent service (macOS LaunchAgent)​

git pull
uv sync
launchctl kickstart -k gui/$(id -u)/com.eidetic-labs.stigmem

Verifying existing data after alignment​

Facts and gardens from older local checkouts live in tenant_id = "default". Confirm with any of your existing API keys:

# Your existing key still works, now in tenant "default"
curl -s -H 'Authorization: Bearer <existing-key>' \
  http://localhost:8765/v1/me
# → {"entity_uri": "...", "permissions": [...], "tenant_id": "default"}

# Facts are still accessible
curl -s -H 'Authorization: Bearer <existing-key>' \
  'http://localhost:8765/v1/facts?limit=5' | jq '.[].id'

Breaking changes​

Not a stable-release upgrade path.

The alpha reset is not a stable-release upgrade path. The supported public surface is v0.9.0a1 plus current main changes queued for later alpha artifacts. Breaking changes may occur until v1.0.0.

The only behavior difference operators will notice is billing events: the LogHookBus now writes a JSON line to stderr for each fact write and garden creation. If your log ingestion pipeline is sensitive to unexpected stderr output, either configure a custom HookBus that discards events or filter the {"billing": ...} lines at your log collector.

Migration history at a glance​

Migration
Status
What it adds
001_init
baseline
Facts, api_keys, node_meta.
002_federation
federation
Peers, nonces.
006_agent_keys
attestation
Ed25519 agent key registration. Required for source attestation.
007_fact_audit
audit
End-to-end audit log. Required for audit queries.
011_facts_garden_attested
required
garden_id + attested columns.
012_multi_tenant
required
tenant_id on all write-bearing tables.

No rollback mechanism.

All migrations run automatically at startup in ascending numeric order. Take a database backup before upgrading if your data is critical.

What's next​

GuideInstallationFresh install with Docker Compose.ReadAudit logQuerying the per-principal write trail.ExperimentalMulti-tenancy pluginTenant isolation model — opt-in package.