> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PLAN project sequence tracker

# Project Sequence Tracker

## Goal

Add an independent workflow tracker for a project and dataset without changing
the existing legacy sequence status.

The tracker is a separate status ledger. It is not a replacement field for
`DatasetSequence.status`.

## PR scope

1. Add project-dataset workflow bindings and project-scoped sequence tracker
   state/history.
2. Add assignment and transition APIs that require project and dataset context.
3. Keep legacy sequence routes and `sequence.status` unchanged.
4. Add tests for both supported cardinalities: one dataset used by multiple
   projects, and one project using multiple datasets.
5. Add tests for independent transitions, permissions, lazy state creation,
   hidden-sequence filtering, and legacy compatibility.

The spike does not include Mission Control UI, export integration, or a
consolidated multi-project view. It is intentionally draft-only until the API,
permission model, visibility rules, and migration receive review.

The PR body links this plan as the encoded design record.

## UI rule

The page must show two separate fields when both exist:

* `Legacy status`: the existing sequence status.
* `Project workflow`: the selected project's tracker status.

Both statuses remain editable through their existing controls. The new tracker
must not make either status read-only. Never merge the two values into one
badge. A project selector is required when the same sequence belongs to more
than one project. The MVP shows one selected project tracker at a time. It does
not show a combined status across projects. The tracker panel is hidden when no
project workflow is assigned.

## Modality rule

The tracker is modality-neutral. The workflow definition declares the modality
and states. Serve can assign a segmentation workflow. Another customer can
assign a cuboid, video, image, or other workflow to its own project.

The first tracker contract is scalar schema version 1. Deliverable schema
version 2 is not flattened into one status. A future deliverable tracker must
store workflow and approval state separately.

## Safety rules

* Do not project tracker transitions into `sequence.status`.
* Do not add sequence transition locks, editor locks, group gates, or
  dataset-name rules.
* This tracker is record-only. It must never block annotation editing, mask
  creation or saving, legacy sequence status changes, dataset writes, or other
  normal work. A tracker error must not fail the underlying work operation.
* Allow an authorized user to select any status declared by the active project
  workflow. Do not require a linear transition path.
* Record every transition in an append-only history table with actor, time,
  previous status, new status, project, dataset, sequence, and reason.
* Preserve existing legacy behavior when no tracker is assigned.
* Create tracker state lazily for the requested sequence. Do not scan or lock
  the full dataset during assignment.
* Deleting a project, dataset, sequence, or user must not be blocked by tracker
  history. Tracker state may be removed, while history keeps its status fields
  and clears deleted foreign-key references.
* Require dataset access and authority on the selected project.
* Do not return tracker state or history for hidden or archived sequences.
  Existing sequence visibility rules must apply before tracker data is returned.
* Restrict workflow revision assignment to staff. Project users can transition
  only the tracker already assigned to their project.

## Relationship cardinality

* One dataset can have an independent tracker binding for each project that
  uses it.
* One project can have an independent tracker binding for each dataset it uses.
* A project and dataset pair has at most one active binding.
* Rebinding a binding after state or history exists is rejected. Create a new
  project tracker for a different workflow revision.