Feature states

Each feature passes through a series of states from creation to runtime. Each state represents a checkpoint in the feature’s integration with the product.

Table of contents

• State machine
• absent
• cached
• declared
• installed
• migrated
• active
• disabled
• See also

---

State machine

                  feature:create
                  feature:clone
                  feature:fork
     (absent) ──────────────────→ [cached]
                                      │
                  feature:add         │        feature:discard
                  feature:attach      ▼        feature:delete
                                 [declared] ─────────────────→ (absent)
                                      │  ▲
               product:resolve /         │  │ feature:remove
               pip install            │  │ feature:detach
                                      ▼  │
                                 [installed]
                                      │  ▲
                   splent db:upgrade  │  │ splent db:rollback
                   splent db:migrate  │  │
                                      ▼  │
                                 [migrated]
                                      │
                 Flask startup        │
                 (FeatureManager      │
                  .register_features) │
                                      ▼
                                  [active]
                                      │  ▲
                      feature:disable │  │ feature:enable
                                      ▼  │
                                 [disabled]

---

absent

The feature does not exist in the workspace. No cache entry, no product reference.

---

cached

The feature exists in .splent_cache/features/<namespace>/<name>/ but has not been linked to any product.

Reached by:

• splent feature:create <ns>/<name>
• splent feature:clone <ns>/<name>
• splent feature:fork <ns>/<name>

---

declared

The feature is registered in the product’s pyproject.toml and a symlink exists under features/. No Python installation has occurred yet.

Reached by:

• splent feature:add <ns>/<name> — editable
• splent feature:attach <ns>/<name> <version> — pinned
• splent feature:install — does both clone + declare
• splent product:resolve — ensures all features have at least “declared”

Reversed by:

• splent feature:remove — returns to cached
• splent feature:detach — returns to cached

At this stage: pyproject.toml has the entry, splent.manifest.json records state: declared. No code is imported, no routes are active.

---

installed

The feature’s Python package and dependencies are installed. The feature is importable.

Reached by:

• The 00_install_features.sh startup script (pip install -e)
• Manual pip install -e .

At this stage: sys.path includes the feature source. Models, services, forms are importable. No Flask app context exists yet.

---

migrated

The feature’s database schema is applied. All its models have corresponding tables.

Reached by:

• splent db:upgrade
• splent db:migrate
• The 03_initialize_migrations.sh and 04_handle_migrations.sh startup scripts

Reversed by:

• splent db:rollback — returns to installed
• splent db:reset — drops all tables and re-applies

Removing a migrated feature requires splent db:rollback <feature> first. The CLI blocks feature:remove, feature:detach, feature:unlock, and feature:upgrade on migrated features unless --force is used.

---

active

The feature is running inside Flask. Blueprints registered, routes exposed, templates and hooks connected.

Reached by: Flask startup — FeatureManager(app).register_features() advances each feature automatically.

This is the only state observable by end users.

---

disabled

Installed (and possibly migrated) but not activated at runtime. Blueprints are not registered.

Useful for gradual rollout, feature flags, or experimental functionality.

---

See also

• State guards — blocked operations and automatic transitions
• Manifest — how state is persisted