Files
PaperClipAI/tests/lifecycle-baseline
Nicky LeachandClaude Opus 5.5 8ab89f41e4 fix(build): typecheck test projects in 4 GiB (#18738)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Contributors and agents typecheck this repository, often on machines
with limited memory
> - paperclipai/paperclip#18737 made `pnpm -r typecheck` fit in 4 GiB
because the server now checks in layers
> - The test projects outside `pnpm -r` still import server source
through relative paths, so each one checks most of the server as one
program
> - These projects peaked between 6.9 GiB and 14.9 GiB, so they fail on
a 4 GiB machine
> - This pull request makes these projects read the server layers as
declarations, and adds a CI step that keeps them that way
> - The benefit is that every TypeScript project in the repository can
now be checked in 4 GiB, and a later change cannot silently undo this

## Linked Issues or Issue Description

Refs paperclipai/paperclip#18737, which is merged. This pull request
builds on the server layers that it added. No issue exists for this gap.

**What happened?**

`tsc -p tests/runner-e2e/tsconfig.json` peaked at 14.9 GiB at default
settings. `tests/speko-native` peaked at 12.2 GiB,
`server/src/__tests__/helpers/maintenance` at 9.6 GiB, and
`tests/lifecycle-baseline` at 6.9 GiB. On one thread, `tests/runner-e2e`
still peaked at 7.7 GiB.

**Expected behavior**

Each project passes with 4 GiB of memory.

**Steps to reproduce**

Run `tsc -p tests/runner-e2e/tsconfig.json` in a Linux container with
`--memory=4g --memory-swap=4g`. The kernel stops the process.

## What Changed

- Added `tsconfig.layers.json` to the four projects. Each file extends
the project's `tsconfig.json` and references the generated server
declarations.
- Added `scripts/typecheck-test-projects.mjs`. It builds the server
declarations and then checks the named projects, or all four. It takes
`--low-memory`.
- Changed `test:e2e:runner:typecheck` and
`test:lifecycle-baseline:typecheck` to call that script.
`docker-runner-check.yml` calls the first script by name, so that
workflow needs no edit.
- Added `--declarations-only` to `server/scripts/typecheck-layers.mjs`.
The script now also generates `tsconfig.declarations.json`, so
hand-written configs do not name individual layers.
- Exported `runPnpm` from `scripts/typecheck-low-memory.mjs`, so the new
script can use it.
- Added a step to the `Typecheck + Release Registry` job. It runs
straight after the server typecheck and reuses its declarations through
`--reuse-declarations`.
- The script now fails if a project loads server source, even when the
types pass. Test support files, declaration files and JSON files do not
count. This check does not enforce a memory limit.
- Added a unit test that fails if a new project under `tests/` is
neither in `PROJECTS` nor named as a single program.
`tests/runner-acceptance` is the one named project.
- Added `server/src/types/express.d.ts` to
`tests/lifecycle-baseline/tsconfig.json`. That plain config failed alone
with 11 TS2339 errors, and it now passes.
- Exported `isTestFile` from `server/scripts/typecheck-layers.mjs`, so
the source check uses the same rule as the layers.
- Turned off `declaration` in the layered configs. These projects emit
nothing, and declaration checks gave a false TS2883 error when
`tests/runner-e2e` read the server as declarations.
- Added tests, one of which runs the real compiler. Updated
`doc/DEVELOPING.md` and `tests/lifecycle-baseline/README.md`.

The references are not in each project's `tsconfig.json` because Vitest
reads that file. A test showed that Vitest fails when a referenced
config does not exist yet. The `tsconfig.json` files do not change, so
editors and Vitest see the same configs as before.

No new `package.json` scripts were added, as `.greptile/rules.md`
requires.

## Verification

I tested commit `9763880fab`, which is based on `1c9ca5829f`. I copied
the commit into a named Docker volume and ran a fresh install. Each row
ran in its own Linux arm64 container with `--memory=4g --memory-swap=4g`
and 8 CPUs. The first row started with no build output. All rows used
`--low-memory`. CI does not set a memory limit. I used the limit only
for this measurement.

| Project | Errors | Peak (cgroup) | Max process RSS | OOM kills | Time
|
| --- | --- | --- | --- | --- | --- |
| `tests/runner-e2e` | 0 | 3.34 GiB | 3.06 GiB | 0 | 57 s |
| `tests/speko-native` | 0 | 3.60 GiB | 3.27 GiB | 0 | 51 s |
| `tests/lifecycle-baseline` | 0 | 3.43 GiB | 3.15 GiB | 0 | 50 s |
| `server/src/__tests__/helpers/maintenance` | 0 | 3.39 GiB | 3.13 GiB |
0 | 52 s |

`PAPERCLIP_TYPECHECK_LOW_MEMORY=1 pnpm test:e2e:runner:typecheck` and
`PAPERCLIP_TYPECHECK_LOW_MEMORY=1 pnpm
test:lifecycle-baseline:typecheck` also passed in the same limit, with
peaks of 3.55 GiB and 3.52 GiB.

I also ran the CI sequence in one container with the same limit: `pnpm
--filter @paperclipai/server typecheck`, then `node
scripts/typecheck-test-projects.mjs --low-memory --reuse-declarations`.
Both passed, with a peak of 3.46 GiB. The new step took 16 s.

The server layer build sets the peak in each row. Against the
declarations, the projects peaked between 0.9 GiB and 2.2 GiB at default
settings on macOS.

Server source files that each project loads, without test support,
declaration or JSON files:

| Project | Plain `tsconfig.json` | `tsconfig.layers.json` |
| --- | --- | --- |
| `tests/runner-e2e` | 1,345 | 0 |
| `tests/speko-native` | 1,647 | 0 |
| `tests/lifecycle-baseline` | 1,343 | 0 |
| `server/src/__tests__/helpers/maintenance` | 1,716 | 0 |

I counted these on `3f0f31b2f9`. The source check in the script
confirmed 0 for all four projects on this commit.

**Limits of this proof:**

- Without `--low-memory`, the 4 GiB run does not pass. The kernel
stopped the layer build for `tests/runner-e2e` on `3f0f31b2f9`, and the
script exited with status 1. I did not repeat this run on the final
commit. The script does not turn on low-memory mode by itself.
- The Linux runs used arm64, not x64.
- The new CI step has not run in CI. `pr-trusted.yml` runs from
`@master`, so the step first runs after this pull request merges. Check
its first run.

**Other checks on this commit:**

- `server/scripts/typecheck-layers.test.mjs`: 38 tests pass. One test
uses the real compiler to show that the source check tells a layered
config from a config with no references.
- With the references removed from
`tests/speko-native/tsconfig.layers.json`, the script exits with status
1 and reports 1,644 server source files.
- With the declarations removed, `--reuse-declarations` exits with
status 1 and reports TS6053.
- A type error in a test project makes the script exit with status 1.
- `tests/lifecycle-baseline/tsconfig.json` passes with 0 errors.
- `tests/lifecycle-baseline` Vitest suite: 533 tests pass.
- Workflow tests that read `pr-trusted.yml` and CI routing: 114 tests
pass.

**Earlier checks:**

- `server/src/__tests__/server-package-build-script.test.ts` passed 10
tests on `3f0f31b2f9`. This test failed in `ci / General tests (server
(9/12))` on an older head. It tested a build script split that the final
#18737 removed.
- A changed signature in `server/src/services/run-liveness.ts` failed
`tests/lifecycle-baseline/authority.test.ts` through the rebuilt
declarations, before the rebases. When I restored the signature, the
check passed.

**Not run locally:**

- `pnpm test:run` and `pnpm build`. CI covers these.

**Failures that this pull request does not cause:**

`pnpm test:e2e:runner:unit` has 13 failures on this commit, in
`cursor-cloud-replay-fault`, `first-task`, `operating-receipts`,
`pi-controls-evidence` and `workflow-security`. The same 13 tests fail
on `master` at `6ef37398c8`. A comparison of the test names shows no
differences. PR CI does not run this suite.

## Risks

- Low risk to runtime behavior. No shipped code changes.
- **Slower check:** `pnpm test:e2e:runner:typecheck` now builds the
server layers on each run. Before the rebase, it took 30 s on macOS at
default settings, about the same as the old single program for that
project. On this commit it took 57 s in low-memory mode in the 4 GiB
container. The new CI step reuses the declarations, so it took 16 s.
- **Narrower check:** Server source is now checked only by the server's
own layers, not again under each project's compiler options. The
projects also skip declaration-portability checks. These projects emit
nothing, so those checks had no output to protect.
- **Unchanged path:** `tests/runner-e2e/native-completion-checks.mjs`
still runs `tsc -p tests/runner-e2e/tsconfig.json` as one program. It
needs about 15 GiB at default settings. I did not change it because that
file and its inputs are part of a fingerprinted source contract, and no
workflow calls it.
- **Layer growth:** The new checks do not measure memory. If the layers
or the import cycle grow, the checks still pass and the peak rises. This
is intentional. Crossing 4 GiB does not fail a build.
- **Project list:** The CI step checks only the projects in `PROJECTS`.
The unit test covers new projects under `tests/`, but not a new project
in another directory.
- **Reused declarations:** `--reuse-declarations` trusts the
declarations on disk. CI uses it straight after the server typecheck on
the same commit. If that typecheck fails, the job stops first. Stale
declarations can pass locally, so `doc/DEVELOPING.md` warns against
this.
- **Job dependency:** A type error in a test project now fails
`Typecheck + Release Registry`, and so `ci / verify`.
- **Not covered:** The new step runs no tests. `node
scripts/typecheck-low-memory.mjs` and the Docker image build also have
no new guard.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Provider: Anthropic. Model: Claude Opus 5.5 (`claude-opus-5-5`),
through Claude Code with tool use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 11:09:12 -08:00
..

Lifecycle behavior baseline

This suite establishes a measurement before removing narrative/regex authority from lifecycle decisions. The original baseline changes no production policy. Assertions describe intended behavior; observed failures are retained rather than blessed as expected outcomes. Subsequent fixes and fresh measurements are recorded separately.

Recorded results moved to paperclip-evals

The 16 saved result JSON files and seven dated measurement reports now live in the lifecycle authority archive in the private paperclip-evals repository. Links below pin the archive commit. The migration manifest records original paths and checksums. JSON measurements are unchanged, including failed and partial attempts; report edits only repair links to application files.

Executable tests, fixtures, graders, run commands, and the scenario inventory remain here. These tests do not require the archive or access to the private repository. New runs still write ignored local output under .lifecycle-baseline/; archive retained measurements in paperclip-evals, with their source revisions and coverage, instead of committing result snapshots to the app repository.

Measurement Archived report (private) Published Product E2E report
September 21 — deterministic baseline Report Deterministic tests; run locally below
September 21 — initial live baseline Report Campaign 35672810261
September 21 — cancellation and fixture fixes Report Campaign 35680906634
September 22 — continuation authority Report Campaign 35747200170
September 22 — explicit work mode Report Campaign 35806360797
September 22 — accounting baseline Report Campaign 35813099816
September 23 — accounting fixes and PR verification Report Campaign 35881382080

The public reports remain available without private-repository access. Each campaign measures its recorded source and selected cells; this index does not combine them into one score or qualify later revisions. Large logs, traces, videos, and browser reports stay in existing campaign artifact storage.

Run and inspect

From an installed Paperclip checkout:

pnpm test:lifecycle-baseline --list
pnpm test:lifecycle-baseline unit
pnpm test:lifecycle-baseline runner
pnpm test:lifecycle-baseline integration
pnpm test:lifecycle-baseline grading
pnpm test:lifecycle-baseline
pnpm test:lifecycle-baseline:support
pnpm test:lifecycle-baseline:typecheck

All four lanes are credential-free. The integration lane uses disposable embedded Postgres and scripted providers. No command above invokes a model, starts a paid campaign, or changes an existing Paperclip instance. Tests are outside default server/workspace discovery; Product E2E matcher calibration remains in its normal opt-in support suite. The baseline command returns nonzero on failed assertions, missing evidence, or unavailable selected coverage. Ordinary CI is unaffected.

Each invocation retains an independent directory under .lifecycle-baseline/:

  • baseline.md and baseline.json: scenario inventory joined to actual assertions;
  • per-lane Vitest JSON: complete assertion results, durations, and failures;
  • observation JSONL: fixture inputs/classifications and actual authority effects, including both sides of narrative pairs and persisted heartbeat outcomes;
  • source.diff: tracked implementation delta from the recorded commit.

The commit plus fingerprint covers tracked differences and untracked authored files. Keep the worktree or commit its tests with retained measurements when comparing revisions. The scripted report marks live coverage not_run; use the separate live Actions record for provider measurements. Authored definitions and passing grader calibration are not proof of real provider behavior. A test suite that cannot load is an evidence/harness failure, not a product finding. Skips are unavailable coverage, never a pass. Failed assertions require triage; raw runner/provider text is not uploaded by this command.

Scenario inventory

inventory.mjs is the executable mapping. References to existing suites reuse their actual assertions rather than duplicating test bodies or counting catalog entries as executed tests. The report records which matching assertions ran.

ID Scenario Contract
LCA-01 Ordinary completion Valid completion, delivered response, no extra execution
LCA-02 Productive multiple turns Continue appropriate work without repeating completed operations
LCA-03 Human question Durable question, matching response, one causal continuation
LCA-04 Approval/decline Correct actor and approval; other admission gates still apply
LCA-05 Planning/revision Work mode and exact accepted revision authorize execution
LCA-06 Dependencies Satisfied dependency condition wakes the parent once
LCA-07 External monitor Durable eligible wait, one-shot wake, bounded expiry/retry
LCA-08 Conversation Deliver the reply without forcing task completion or repair loops
LCA-09 Missing disposition Bounded explicit repair; comments/restarts do not reset attempts
LCA-10 Stop/pause/budget Preserve distinct semantics; no unauthorized continuation
LCA-11 Terminal ordering Completion report, provider terminal, and cleanup remain distinct
LCA-12 Replay/restart/ownership Preserve receipts and budgets; fence stale finalizers
LCA-13 Review Concrete reviewer/owner and authoritative review outcome

Troublesome combinations included in the inventory and reused suites:

  • Completion followed by failure/cancellation or stream closure without terminal.
  • Approval while paused/over budget; response arriving during input handoff/cleanup.
  • Reassignment/closure before late finalization; restart between commit and delivery.
  • Exhaustion followed by commentary versus an authorized new user request.
  • Stale plan revision approval; duplicate question/dependency/reconciler events.
  • Wrong company/task or unauthorized resolution; productive versus failure retries.

Narrative pairs and positive controls

authority.test.ts records the legacy classifier for diagnostic comparison and executes the production structured continuation decision. Assertions compare scheduling decisions rather than requiring diagnostic labels to be identical. The persisted legacy authority tests cover replay, restart, exhaustion and dispatch gates; they also run in the ordinary server suite. Native pairs exercise the actual status arbiter. The heartbeat cases cross the real persistence/finalization boundary for both runtimes, including explicit native continuation and the legacy missing-disposition path. Observations precede cleanup; a second queue/drain pass checks for additional dispatch. This is not proof about arbitrary future timers: the existing monitor/retry/reconciler suites separately exercise due-time policy.

Vary summaries/results, existing comment bodies, continuation summaries, stdout, stderr, titles, and descriptions. Variants cover negation, historical quotation, Spanish, optional next steps, unsupported completion claims, encouraging prose, and empty narrative. Commentary-only evidence must not manufacture progress. Keep authority identical for each pair. Positive controls change real status, approval, continuation, budget, or ownership with identical prose. New authenticated user messages are separate causal events, not interchangeable text.

Scripted runner tests validate actual session/event behavior and structured-result contracts. They do not prove OS termination or real provider compliance. Native replacement tests inject verifier evidence at their documented boundary. Route unit tests mock services; database suites test persisted application behavior. These proof boundaries must remain visible when interpreting the baseline.

Live evals

The dedicated live lifecycle suite adds 40 explicitly selected real-LLM/browser cells on both runtime generations. It was authored after the initial scripted baseline and has now run on GitHub Actions; see the separate live record for measured outcomes. Use pnpm test:e2e:runner -- --list --suite lifecycle-baseline to inspect it.

Product E2E uses the existing continuation, agent-chat, and everyday-workflows catalogs. Continuation now retains an explicit lifecycle snapshot at each browser checkpoint and grades pending question identity, plan revision binding, original run receipts, and the absence of execution/recovery paths after completion. The grader has valid/wrong/missing-evidence calibration. The continuation definition version advances so measurements are distinguishable.

Validate/discover without spending:

pnpm test:e2e:runner:typecheck
pnpm test:e2e:runner:unit
pnpm test:e2e:runner -- --list --suite continuation
pnpm test:e2e:runner -- --list --suite agent-chat
pnpm test:e2e:runner -- --list --suite everyday-workflows

The sibling paperclip-evals change adds the opt-in rosters/live-lifecycle-narrative-baseline.json: ordinary finish/block controls, two misleading-summary variants, and question/review/dependency/wake cases. It does not expand the maintained paid campaign. Both cases and the roster are validated without providers; successful, wrong-state, missing-tool, and extra-wake evidence calibrate their actual grader.

For subsequent live execution use existing explicit selectors and record exact App/Evals revisions, profile/environment, retries, usage/cost, and artifact IDs. See doc/evals.md. Do not combine mock-authority Runner Eval scores with Product E2E scores, or claim full qualification from a partial selection.

September 22 follow-up: legacy continuation implementation and verification, including preserved failed campaigns and the remaining backlog.

The continuation accounting matrix adds ACCT-01 through ACCT-04 for separate allowances, false progress, late gates and restart/replay. Its real-provider companion is the explicit-only continuation-accounting Product E2E suite. The September 22 measurement records the enabled failures and preserves both initial and corrected live campaigns. The September 23 fixes and fresh verification retain the original measurements and cover separate persisted allowances, delayed repair promotion and the current native question/response continuation contract.

The inexpensive browser regressions use real Chromium without a provider or Paperclip instance. They check screenshot readiness and development service-worker module revalidation across repeated reloads:

pnpm exec playwright test --config tests/runner-e2e/playwright-support.config.ts

Set PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome to use an installed Chrome browser.