causet projections

Proposed: All causet projections subcommands are on the roadmap. See Roadmap.

Commands for inspecting and managing the state of your projections.

`causet projections list`

List all projections defined in the active IR for a fork, with their current status.

causet projections list \
  --platform my-platform \
  --app concert-app \
  --fork main \
  --env production

Planned output:

PROJECTION                 STATUS    LAG     LAST PROCESSED
user_following             healthy   0s      2s ago
artist_show_directory      healthy   0s      2s ago
venue_stats                degraded  45s     47s ago
user_concert_memory        failed    --      3h ago

Column	Description
`STATUS`	`healthy` / `degraded` / `failed`
`LAG`	Current consumer lag in seconds
`LAST PROCESSED`	Time since last successful event processed

`causet projections doctor`

Validates projection health against a set of checks. Intended as a deployment gate — run before promoting a release to production.

causet projections doctor \
  --platform my-platform \
  --app concert-app \
  --fork main \
  --env production \
  --fail-on-error

Checks performed:

All projection tables exist in the tenant schema
All required indexes exist
Checkpoint store is reachable and has records
Fixture replay produces expected results (if fixtures are defined)

Example output:

✓ Loaded 24 projections
✓ Verified checkpoint store
✓ Verified projection tables
✕ user_concert_memory failed fixture replay
✕ venue_stats missing index idx_venue_stats_venue_id

2 checks failed. Deployment blocked.

Flags:

Flag	Description
`--platform <p>`	Platform identifier
`--app <a>`	Application identifier
`--fork <f>`	Fork to check
`--env <name>`	Target environment
`--fail-on-error`	Exit 1 if any check fails (for CI use)

Exit codes:

Code	Meaning
0	All checks passed
1	One or more checks failed

CI integration:

# GitHub Actions — deployment gate
- name: Projection health check
  run: |
    causet projections doctor \
      --platform my-platform \
      --app concert-app \
      --fork production \
      --env production \
      --fail-on-error

`causet projections replay`

Rebuild a specific projection by resetting its Kafka consumer offset.

causet projections replay \
  --projection user_following \
  --platform my-platform \
  --app concert-app \
  --fork main \
  --env production

The command prompts for confirmation before resetting the offset — this is a destructive operation.

This will truncate the 'user_following' table and reset the consumer offset.
All existing rows will be deleted and rebuilt from the event stream.

Type the projection name to confirm: user_following

Flags:

Flag	Description
`--projection <name>`	Projection to replay
`--from-beginning`	Reset to the earliest available offset (default)
`--from-timestamp <ts>`	Reset to a specific timestamp
`--no-confirm`	Skip confirmation prompt (for scripted use)

After reset, monitor progress via Kafka consumer lag:

kafka-consumer-groups.sh \
  --bootstrap-server $KAFKA_BOOTSTRAP \
  --describe \
  --group causet-projection-worker

Replay is complete when consumer lag reaches 0.

Warning: Do not replay projections that trigger external side effects (notifications, billing). Replaying will re-execute those effects.

`causet projections failures list`

List open projection failures.

causet projections failures list \
  --platform my-platform \
  --app concert-app \
  --fork main \
  --env production

Example output:

ID              PROJECTION        EVENT TYPE      ENTITY ID    FAILED AT
fail_01j2x...   user_following    ARTIST_FOLLOWED  user-999    2026-06-25 12:01:03
fail_01j2y...   venue_stats       SHOW_ANNOUNCED   artist-101  2026-06-25 11:59:12

Flags:

Flag	Description
`--projection <name>`	Filter by projection name
`--limit <n>`	Max failures to show (default: 50)
`--resolved`	Include resolved failures

`causet projections failures retry`

Retry a specific projection failure record. Replays the failed event through the projection handler.

causet projections failures retry \
  --id fail_01j2x... \
  --env production

Flags:

Flag	Description
`--id <failure-id>`	Failure record ID from `failures list`
`--all`	Retry all open failures (use with caution)

What is Causet?