Adapstory Developer Docs

Plugins have a deterministic lifecycle owned by BC-02 (Plugin Lifecycle). Understanding it is the difference between a smooth upgrade and a 3 a.m. rollback page.

States

DRAFT ──▶ SIGNED ──▶ VERIFIED ──▶ INSTALLING ──▶ ACTIVE
                                       │             │
                                       ▼             ▼
                                    FAILED       UPGRADING ──▶ ACTIVE
                                       │             │
                                       ▼             ▼
                                   ROLLED_BACK   ROLLED_BACK

DRAFT — you pushed an image, but haven't signed it.
SIGNED — Cosign signature present, SBOM attached.
VERIFIED — BC-02 verified the signature chain + SLSA provenance. Installable.
INSTALLING — BC-19 is provisioning namespace, secrets, network policy. Pod starting.
ACTIVE — probes green, MCP tools registered with BC-01.
UPGRADING — new version rolling out with blue/green or canary (your choice).
FAILED / ROLLED_BACK — explicit terminal states. Audit log has the reason.

Publishing a new version

adapstory plugin build --version 0.2.0     # builds image + SBOM
adapstory plugin sign                      # Cosign + SLSA
adapstory plugin publish                   # → VERIFIED

Publishing does not install. Tenants or admins install explicitly, or an install-policy auto-promotes.

Install policies

Tenants can set:

pinned — only installs the exact version they chose.
minor-auto — auto-installs minor bumps of the same major.
canary — installs to a percentage of users first, promotes on health.

Set in admin UI or via adapstory tenant set-policy.

Upgrade strategies

Declared in spec.runtime.upgrade:

spec:
  runtime:
    upgrade:
      strategy: canary            # canary | blueGreen | rolling
      canarySteps:
        - { weight: 10, pauseSeconds: 300 }
        - { weight: 50, pauseSeconds: 600 }
        - { weight: 100 }
      healthGate:
        slo:
          errorRate: 0.01
          p99LatencyMs: 300

If the SLO breaches at any step, BC-02 auto-rolls back.

Rollback

Manual:

adapstory plugin rollback hello-learner --tenant <tid> --to 0.1.9

Automatic: health gate failure, Kyverno denial, or 5-consecutive-restart crash-loop.

Rollbacks only go backwards through known-good versions (previous ACTIVE state). You can't roll back to a version that was never activated in this tenant.

Schema migrations

If your new version changes the data model (BC-15), BC-02 runs migrations before pod rollout.

Rules:

Additive migrations (new column, new index): auto, forward-compatible.
Renames / type changes: require a two-version migration — v1.2 adds the new, v1.3 drops the old.
Destructive migrations (drop column, drop table): require explicit admin approval.

If a migration fails, the whole install or upgrade fails — the old version keeps running.

Decommissioning

To remove a plugin from a tenant:

adapstory plugin uninstall hello-learner --tenant <tid>

This:

Unregisters MCP tools from BC-01 (LLMs stop seeing them immediately).
Drains Kafka consumers.
Waits 30s for in-flight calls to finish.
Deletes the namespace (and secrets — Vault copies are kept).
Marks the install RETIRED in audit.

Data in BC-15 schemas is retained unless the admin explicitly requests deletion.

Multi-tenant rollouts

When you publish version 0.2.0, tenants don't upgrade in lockstep — each respects its own install policy. You can track real-world health per version:

adapstory plugin stats hello-learner

Output: tenants on each version, error rates, LLM spend, p99 latency.

Next: Observability.

Lifecycle & deployment