Skip to content

Add a bounded read-only lifecycle HTTP API #20

Description

@Punisheroot

Context

The lifecycle store can load one canonical projection by change ID and replay
its ordered event journal. It does not yet expose a bounded list query, and the
local control plane has no lifecycle HTTP surface. The domain already enforces
MAX_LIFECYCLE_EVENTS, so this issue does not need to invent a second event
cursor protocol. The timeline UI remains a separate issue.

Outcome

Expose authenticated, deterministic, read-only lifecycle list, detail, and
event responses from the authoritative SQLite store. Responses use explicit
safe DTOs and contain no credentials, raw transcripts, artifact bytes,
canonical repository roots, or unbounded history.

Scope

  • Add a bounded store query for lifecycle summaries with deterministic ordering
    and a documented hard maximum.
  • Add versioned GET routes for the bounded list, one lifecycle identified by its
    change ID, and its already hard-bounded ordered events.
  • Map domain/store values into explicit HTTP response types; never serialize
    persistence rows or the full internal domain object directly.
  • Return lifecycle identity, phase/status, state digest, source/profile/test-plan
    identities, bounded usage, artifact references, terminal reason, and
    redacted cleanup/recovery state when present.
  • Follow existing server authentication, error-envelope, module, and route-test
    patterns.
  • Add tests for empty state, missing/malformed ID, deterministic list order and
    limit, event order, corruption/unknown-value rejection, redaction, and bounds.

Non-goals

  • Starting, advancing, cancelling, approving, applying, or retrying a lifecycle.
  • Server-sent events, polling policy, timeline UI, patch blobs, raw provider or
    worker transcripts, credentials, or absolute repository paths.
  • Changing lifecycle transitions or creating another lifecycle source of truth.
  • Adding cursor machinery while the domain event journal is already strictly
    bounded.

Acceptance criteria

  • The store exposes a deterministic bounded lifecycle-summary query without
    changing lifecycle state.
  • List, detail, and events routes read only from the lifecycle store and
    identify the domain consistently by change ID.
  • Event output preserves canonical sequence and never exceeds the existing
    domain bound.
  • Explicit safe DTOs omit secrets, raw transcripts, artifact bytes, and
    canonical repository paths.
  • Missing resources, malformed IDs, corruption, and invalid limits use the
    existing bounded HTTP error contract.
  • Tests prove authorization, redaction, ordering, bounds, and zero lifecycle
    database writes.
  • Existing control-plane and role-profile HTTP behavior is unchanged.

Starting points

  • crates/needle-runtime/src/store/lifecycles.rs
  • crates/needle-app/src/server.rs
  • crates/needle-app/src/server/role_profiles.rs
  • crates/needle-app/src/server/role_profiles/tests.rs

Validation

Run focused lifecycle-store and new server-route tests. Build the embedded
frontend before compiling needle-app from a clean checkout. No provider or
browser run is required.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: agentsSubagent roles and orchestrationarea: webWeb application and local control planecodex-firstCodex-first development scopeenhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions