Metadata-Version: 2.4
Name: party-continuum
Version: 0.10.9
Summary: Change impact from Party's Continuum: what a change reaches, how risky it is, which tests reach it
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.29,>=0.28

# continuum

Change impact from Party's Continuum, for people and coding agents: what a
change reaches, how risky it is, which tests reach it, and what no test reaches.
Continuum keeps a dependency graph of each repository current as its default
branch changes; this CLI asks it about your checkout.

```bash
pip install party-continuum        # or: brew install maitai-inc/continuum/continuum
continuum login                    # a browser code; saves a revocable token
```

Before an edit:

```bash
continuum dependents billing/charge.py::charge --depth 2   # what depends on it
continuum impact --plan charge --change signature          # the reach of a planned change
```

After an edit (the working tree against the default branch):

```bash
continuum impact      # reach, impact and risk grades, and what drives them
continuum tests       # every test that reaches the change, with commands to run them
continuum untested    # reached code that no test reaches: add tests here
continuum explain api/refunds.py::refund   # why the change reaches it
```

Every command takes `--json`. `--repo owner/name` overrides the checkout's GitHub
origin, and `--base` / `--head` choose what to compare.

**Impact and risk are separate.** Impact is how much behavior the change can
reach. Risk is how much of that no test would notice: reached code no test
reaches, code still using something the change removes, and changes Continuum
cannot see through. A wide, well-tested change is high impact and low risk; a
small change to untested code is the reverse. Both are graded against the
repository's own recent changes.

**What it sends.** The paths of your changed files and the contents of changed
text files (at most 4 MB); never other files, and nothing unless you run a
command. The graph lives with Continuum, so answers take about a second.

**Tokens.** `continuum login` saves a token that reads Continuum and nothing
else; logging in again or using it keeps it alive, and `continuum logout` revokes
it. For CI and agent Environments, create a fixed token and set it as
`CONTINUUM_TOKEN`:

```bash
continuum token create --name "skipper Environment" --repo maitai-inc/skipper --days 90
continuum token list
continuum token revoke <id>
```

Requirements: Python 3.11+ and git. Installation also installs HTTPX. Each CLI
command reuses a private HTTP/1.1 connection pool for authenticated API calls,
then closes it on exit. System certificate trust and environment proxies remain
supported. Event streams retain their held-open transport. Repository bootstrap
scripts that import the client before installing dependencies retain the stdlib
request path until HTTPX is available. Continuum is for members of the Party
organization; `CONTINUUM_URL` points the CLI at another Party server.

## Building the CLI

Run `python continuum/cli/stage.py --version 1.2.3 --out build/party-continuum`,
then `python -m build build/party-continuum`. Staging requires Node.js 22 and npm.
It bundles the locked GitHub artifact SDK with its licenses into the package.
The wheel and source distribution include the complete uploader for both Linux
amd64 and arm64. Protected runner jobs execute it with Node.js 22.

CI also builds a self-contained runtime image for Linux amd64 and arm64. It
contains Python 3.12, Node.js 22, Git, the Docker client, the CLI and its Python
dependencies. The protected job launches this image against its workspace and
Docker daemon. Repository test containers run with their own images. The runtime
launcher preserves host paths for source and Git-object mounts and cleans up
containers belonging to the job on exit.

Every CLI change pushed to main automatically produces a downloadable
`party-continuum` Actions artifact containing a development wheel and source
distribution. Pull requests build the same artifacts. The workflow verifies
installation, artifact upload and retry on both architectures. Dispatching
`Build and publish Continuum CLI` with a release version publishes those same
bundled files to PyPI when publishing is enabled.

## Setup and trusted development checks

`continuum login --validation` installs missing repository agent instructions; use
`--no-skill` to opt out or `continuum init` to install later. Custom skills are
preserved. `continuum doctor` diagnoses configuration without claiming a live
execution succeeded. Headless keys can also be created in dashboard Settings.

CLI upgrades do not replace an existing `.agents/skills/continuum/SKILL.md`;
`continuum init` preserves it even if it came from an older CLI. To refresh an
existing skill, merge the current template's guidance from
`party_continuum/setup.py` into that file, keeping repository-specific instructions.
In particular, older skills need the `index_pending` polling and retry guidance.

`continuum validate run --stage build` submits the frozen working snapshot and
phase to the Continuum API, follows progress, and returns the verdict. The service
owns selection, input-based pass reuse, runner dispatch, concurrency, cancellation
and results. Validation uses the actual merge base, including after a rebase.
If that baseline is not indexed, it returns `index_pending` with the index job
and ETA rather than adding intervening main changes to the branch's ledger.
Poll `continuum status --at COMMIT --json` using `index_job.commit`. Rebasing
retains prior branch evidence for tests unaffected by the actual tree delta. Agents need a validation token; they need no GitHub dispatch access,
executor credential or Docker. Source submission uploads only changed blobs and
deletions; the service verifies the resulting Git tree against the baseline.

If no compatible baseline is indexed, validation exits nonzero immediately with
JSON containing `status: "index_pending"` and `index_job`. It joins an active
baseline indexing job or queues one atomically; it does not retain a validation
request or launch tests. Retry validation once indexing finishes.
`continuum status --json` reports the current job without starting or retrying it.
The job includes `id`, `commit`, `analyzer`, `status`, `stage`, `date_started`
(UTC ISO 8601, or null before indexing starts), `time_remaining` (estimated seconds), and
`retry_after` (suggested polling seconds). Estimates use recent repository index
durations, including publication and queued work. `time_remaining` is null when
history is unavailable or an estimate has been exceeded; it is not a deadline.
An explicit validation retry can requeue failed indexing. API clients can use
`POST /repos/{owner}/{name}/validations` with `{"ensure_index": true}` for the same
preflight: 200 when ready, or 409 with the indexing job. Both validation submission
endpoints perform this check before admitting planning work.

For asynchronous execution:

```bash
continuum validate run --stage build --detach
continuum validate watch RUN_ID
continuum validate watch RUN_ID --events-json --after 42
continuum validate run-status RUN_ID
continuum validate stop RUN_ID
```

Disconnecting a watcher does not cancel execution. Requests are idempotent and
reconnect to accepted planning or execution after a lost response. Admission,
leases, cancellation and outcomes are durable; a restart resumes the same request
identity. Planning has a bounded service deadline and cannot publish new work
after cancellation or lease loss. After a confirmed planning failure, explicitly
rerunning the command retries that identity; uncertain or active submissions
reconnect instead. Event cursors survive service restarts. GitHub gets normal streamed logs, failure annotations, a job summary and
links to runner logs. Failed tests produce a failing verdict. Default terminal
output summarizes phase counts and failures; add `--json` to `run`, `watch` or
`run-status` for the complete ledger and execution graph.

Repository policy chooses local or runner build execution. `--execution local`
explicitly launches the separate `continuum-runner` adapter in the coding
environment; it pulls work from the same service and does not start Docker.
`--execution runner` uses service-managed GitHub/Blacksmith execution. The service
enforces allowed locations and worker limits. Local passes satisfy the ledger
only when the baseline explicitly trusts them; otherwise they remain observations.
PR/merge phases require protected runner execution. Prepared runtime images own
runner dependencies. See [operator setup](../VALIDATION_LEDGER.md).

Successful analysis can identify an uncertain dependency boundary that requires
a reviewed conservative suite. A planning error, missing baseline or timeout is
reported to the caller and never produces a broader execution plan. Responses include `selection.mode`, `reasons`,
`phase` and `suites`; the dashboard labels conservative runs and their reason.
A setup without executable suites is a configuration error, never an empty pass.

A pre-submission availability failure exits 75 so GitHub can invoke the
user-defined complete-phase fallback. Lost submission responses or interrupted
watches do not authorize duplicate fallback runs: reconnect first. If the CLI
or service cannot be used, agents can run documented repository tests themselves;
report the snapshot, commands, outcomes and skips separately from hosted evidence.
A test failure cannot become a pass through fallback.

After edits, repeat `continuum validate run --stage build`. The service retries
failed/unfinished work and invalidates passing results only when relevant inputs
changed. `reuse = "dependency-inputs"` permits verified per-test file-dependency
reuse; `exact-tree` remains the conservative boundary when dependencies cannot be
proven complete. Whole suites and unsupported reporters keep command-level receipts.

The durable admission and branch-lineage service requires PostgreSQL migration
023 (SQLite 017). Hosted execution retains API run protocol 1, a released
CLI/runner 0.6.0+, an admitted immutable runner workflow and the
GitHub App's repository-scoped Actions write permission. Index access retains its
separate read-only credential. Install the generated setup PR before activating
new callers; legacy workflows remain independently pinned during that rollout.

## Phase override labels

A pull request label `continuum:<phase>=<mode>` sets the mode for that pull
request's own CI run of the phase, ahead of the merged policy, the service
switch and the delegation blockers. Phases are `pr`, `merge` and `post-merge`;
modes are `off`, `shadow` and `delegate`.

- The gate sends which run it is with its status request: the pull request
  number, the merge-queue ref, or the pushed range. The service reads the
  labels and answers with the effective mode and an `override` naming the label.
- A merge-queue run belongs to the pull request its ref names
  (`gh-readonly-queue/<base>/pr-<number>-<sha>`); labels on other pull requests
  in the group are not read.
- A push to the default branch honours a `post-merge` label only when it landed
  exactly one pull request. Otherwise the repository's setting applies.
- With several labels for one phase, the most recently added applies.
- Labels that cannot be read hand the run to the workflow's original jobs
  (`reason: labels_unreadable`), since one of them may say `off`.
- A gate called with `--delegate-only` does not start shadow work, so `shadow`
  there runs the original jobs only.

The service's GitHub App needs read access to pull requests. Agents apply these
labels only on an explicit request; the installed skill says so.

## Native GitHub continuations

Repositories with external requirements can opt into
`python -m party_continuum.phase_gate --delegate-only --native-workflow .github/workflows/ci.yml`.
After managed targets finish, the gate reserves outstanding work and emits
`candidate` and `native_matrix` (job name, profile, runner labels). A pending
`native_assignments` result retains service ownership; it is not a passing verdict.

Each matrix job runs `python -m party_continuum.native_jobs CANDIDATE --stage pr
--workflow .github/workflows/ci.yml --job JOB --reports DIRECTORY`. The reviewed
policy supplies its command, setup, runner labels and exact GitHub job mapping.
The adapter exports `CONTINUUM_SNAPSHOT_ROOT` and `CONTINUUM_GITHUB_VARIANT` for
repository-owned setup. It executes only reserved outstanding requirements.
Upload the reports even on failure, using the artifact prefix and upload-step
name declared in `github_reports`. A final job imports completed jobs with
`continuum validate record-github CANDIDATE --head "$GITHUB_SHA" --stage pr --partial`
and requires `continuum validate status CANDIDATE --require-stage pr`.

The gate and native jobs need the Continuum token, GitHub read token and OIDC
permission for reservations. Test subprocesses do not inherit those tokens.
GitHub verifies outcomes; the adapter never submits container attestations.
Keep the repository's independent fallback graph for service unavailability.
