Feature state — splent.manifest.json

Every product has a splent.manifest.json file that tracks the lifecycle state of each feature. It is the authoritative record the CLI and startup scripts use to answer “what state are my features in?”.

Location
What it governs
Format
Field reference
Lifecycle states
When it is updated
Who reads the manifest
Inspecting feature state
See also

Location

<workspace>/
└── <product_name>/
    ├── pyproject.toml
    ├── splent.manifest.json   <- here
    └── src/

What it governs

pyproject.toml declares which features a product uses. The UVL declares which combinations are valid. splent.manifest.json tracks where each feature stands in the lifecycle pipeline:

Question	Answered by
Which features does this product include?	`pyproject.toml`
Is this combination valid?	UVL
Is each feature installed, migrated, active?	`splent.manifest.json`

Format

{
  "product": "sample_splent_app",
  "schema_version": "1",
  "updated_at": "2026-03-23T12:00:00Z",
  "features": {
    "splent_io/splent_feature_auth@v1.2.7": {
      "namespace": "splent_io",
      "name": "splent_feature_auth",
      "version": "v1.2.7",
      "mode": "pinned",
      "state": "declared",
      "declared_at": "2026-03-23T12:00:00Z",
      "installed_at": null,
      "migrated_at": null,
      "updated_at": "2026-03-23T12:00:00Z"
    },
    "splent_io/splent_feature_redis@v1.2.7": {
      "namespace": "splent_io",
      "name": "splent_feature_redis",
      "version": "v1.2.7",
      "mode": "pinned",
      "state": "active",
      "declared_at": "2026-03-22T09:00:00Z",
      "installed_at": "2026-03-22T09:05:00Z",
      "migrated_at": null,
      "updated_at": "2026-03-23T10:00:00Z"
    }
  }
}

Field reference

Field	Description
`namespace`	Filesystem-safe namespace (`splent_io`, `myorg`)
`name`	Feature package name (`splent_feature_auth`)
`version`	Pinned version tag, or `null` for editable
`mode`	`"pinned"` (versioned release) or `"editable"` (development)
`state`	Current lifecycle state: `declared`, `installed`, `migrated`, `active`, `disabled`
`declared_at`	When the feature was first added to the product
`installed_at`	When `pip install` completed (set by startup scripts)
`migrated_at`	When `db:upgrade` completed (set by startup scripts)
`updated_at`	Last time this entry was modified

Lifecycle states

Features progress through a linear pipeline. Each state represents a layer of the system:

declared  →  installed  →  migrated  →  active
                                          ↓
                                       disabled

State	Layer	What it means
`declared`	Configuration	Registered in `pyproject.toml`, symlink exists, not yet installed
`installed`	Environment	Python package installed, code is importable
`migrated`	Persistence	Database schema applied, tables exist
`active`	Runtime	Blueprints registered, routes exposed, fully operational
`disabled`	Runtime	Installed (possibly migrated) but not activated — blueprints are skipped

For the full lifecycle diagram and detailed state descriptions, see Feature lifecycle.

When it is updated

Operation	Manifest change
`splent feature:add`	Entry created with `state: declared`
`splent feature:attach`	Entry created with `state: declared`
`splent feature:remove`	Entry removed
`splent feature:detach`	Entry removed
`00_install_features.sh`	State advanced to `installed`
`04_handle_migrations.sh`	State advanced to `migrated`
Flask startup	State advanced to `active`

Who reads the manifest

Consumer	What it reads	Why
`feature:status`	Full manifest	Displays lifecycle progress table
Startup scripts (`00_install_features.sh`, `04_handle_migrations.sh`)	`state` per feature	Decides which features need installation or migration
`splent_framework` (FeatureManager)	`state` per feature	Skips `disabled` features during registration
`doctor`	Full manifest	Cross-references against `pyproject.toml` for consistency

Inspecting feature state

Use feature:status to view the manifest as a human-readable table:

splent feature:status

  Feature status — sample_splent_app
  ──────────────────────────────────────────────────────────────────
  Feature                                    Mode      Progress       State
  ──────────────────────────────────────────────────────────────────
  splent_io/splent_feature_auth@v1.2.7       pinned    ●─●─●─●        active
  splent_io/splent_feature_public@v1.2.7     pinned    ●─●─●─●        active
  splent_io/splent_feature_redis@v1.2.7      pinned    ●─●─○─○        installed
  splent_io/splent_feature_mail@v1.2.7       pinned    ●─○─○─○        declared

Progress dots represent: declared ─ installed ─ migrated ─ active

Pass --json to output the raw manifest:

splent feature:status --json

If splent.manifest.json does not exist, feature:status falls back to reading pyproject.toml and reports all features as declared.