Check before sharing

Set up publication checks

Checks keep a whole outgoing package local until it passes your project’s validation. You keep editing in your usual tools. Your teammate continues to receive accepted changes, and repairing a failed check automatically starts another attempt.

cor checks init --preset threejs
docker pull node:22-bookworm-slim
cor check

The preset configures strict JSON parsing, PNG/JPEG/WebP decoding, incremental TypeScript checking when a tsconfig exists, your existing build and check scripts, and Khronos GLB/glTF validation. It requires an npm lockfile. TypeScript reads JSONC compiler settings itself; those files are excluded from strict JSON parsing. Other package managers can use custom commands.

cor checks init detects Three.js, Node, or Rust, falling back to assets. The Rust preset uses cargo check --locked --offline --all-targets and keeps Cargo’s build cache. Pull its rust:1-bookworm runner image before the first check. cor install --checks auto combines installation and configuration.

cor current --checks /path/to/project/corotation.json

Current saves its required policy privately. Subsequent starts need only cor current. Each teammate inspects the shared configuration and runs cor checks trust once. Editing or deleting the shared policy cannot silently disable approved checks. Clients with a different policy stay blocked.

cor work

Existing projects continue to sync without validation until checks are configured. Enabling a policy does not certify historical baselines.

How checks stay incremental

Corotation captures a candidate using its existing chunk manifests. A separate validation workspace receives only changed files; unchanged source files retain their timestamps. Your working folder is never used as a build sandbox.

• Results are cached by declared input contents, check configuration, preparation inputs, and toolchain identity. Adding or deleting a matching input also invalidates the result.
• TypeScript retains its .tsbuildinfo; Cargo retains its target directory. Build outputs and dependencies remain in the validation workspace.
• Dependency installation runs only when the preparation inputs or toolchain change. npm presets use the lockfile and disable installation scripts.
• JSON and image checks reuse per-file results. Model validation uses chunk-derived identities and referenced-resource identities, avoiding reads of unchanged large assets.
• Failed checks also remain cached for the same inputs. Save a repair to retry automatically, or request a fresh run after fixing the environment.

Corotation does not turn an arbitrary full-build command into an incremental compiler. The generated build check uses all project inputs because a bundler may import assets or custom configuration. For an expensive build, configure a project-specific incremental validation command and declare its complete dependencies. Do not exclude files merely to hide a failure.

cor checks retry

This invalidates local and configured remote check caches. cor check --fresh invalidates only local caches and runs immediately. Only the active validation workspace is retained. A fresh run or toolchain/policy change retires old scratch copies under the engine lock; source chunks and baselines are preserved.

Add a custom check

Add entries to checks.checks in corotation.json. Commands run with an argument array, without an implicit shell. Exit zero passes; a nonzero exit blocks publication by default.

{
  "name": "scene-smoke-test",
  "run": {
    "kind": "command",
    "argv": ["npm", "run", "check:scene"]
  },
  "inputs": ["src/**", "assets/**", "package*.json", "tsconfig*.json"],
  "timeout_seconds": 60,
  "blocking": true
}

Inputs are glob patterns over the entire proposed project, not just the changed paths. The default is ["**"]. Prefix a pattern with ! to exclude it. Include imported files, scripts, configuration, lockfiles, and any other input that could change the outcome. A custom check is only as complete as its dependency declaration.

The policy also has version: 1, a runner, an environment map, prepare command arrays, and prepare_inputs globs. Use {cache} in arguments or environment values or LAPLACE_CACHE inside scripts for persistent scratch data. Checks must not rewrite captured source files; write generated output separately. Use blocking: false only for advisory checks.

After changing the policy, inspect and approve it with cor checks trust on each client, then restart current with --checks to pin the new policy. An incoming package cannot alter the server’s required checks.

Runners and limits

Presets use Docker-compatible containers; Colima works on macOS. Each run resolves the image to an immutable local image ID, which participates in cache invalidation. Checks have no network, a read-only container filesystem, two CPU cores, 2 GiB memory, a 256-process limit, and a bounded temporary directory. They can access only their scratch workspace and cache. No project credentials or Docker socket are mounted. Dependency preparation can access the network.

For trusted local code on Unix, {"kind":"native","toolchain":"my-node-toolchain-v1"} avoids containers. Native commands receive a filtered environment, but are not an operating-system sandbox. Executable contents are fingerprinted; bump the explicit toolchain key when transitive system tools or libraries change. A server requires --allow-native-checks to run native commands.

Built-in JSON parsing accepts files up to 64 MiB. Image checks cap encoded files and decoded allocations at 256 MiB, and dimensions at 32,768 pixels. Larger formats can use custom command checks. Timeouts default to 120 seconds per check, with a 600-second total candidate deadline. Missing tools, runner errors, and timeouts fail closed. Logs are bounded. Commands must terminate; background children are stopped. Required checks serialize on current while reads, downloads, and baseline creation remain available.

Failures and agent repair

cor checks
cor checks --watch --json
cor status --json

checks.laplace.json reports candidate identity, policy, origin, check results, diagnostics, timing, and cache reuse. It is a local projection of .laplace/checks-report.json. Both are excluded from synchronization, and setup excludes the public report from Git.

A failed check is different from a conflict. Repair the working files and save; leave cor work running. The installed agent helpers follow this same process within your task. An overlapping incoming edit preserves both versions and blocks the entire affected local batch for explicit conflict resolution.

A candidate is checked locally before upload. Current independently checks its latest accepted tree plus the proposed whole package. This catches separately valid edits that fail when combined. Uploaded chunks are not visible as project files until publication succeeds. An accepted or rejected request retains its idempotent receipt across retries.

When valid is not yet finished

cor hold
# Make the complete change.
cor resume

Hold persists across restarts. Safe incoming changes still arrive. A package already submitted can finish; hold does not retract it.

Checks certify the configured validations, not all gameplay behavior or the completion of your intent. Add relevant smoke tests for those behaviors. Publication is atomic on current; clients still apply the package’s files individually, so an already-running application can briefly observe an installation in progress.