npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@holland-vip/causet

v0.27.0

Published

An experimental causal source-control layer over Git, as the cst command: records how changes move between Git histories, with verifiable receipts, declared provenance, and portable metadata. Prebuilt for Windows x64 and Linux x64 (glibc).

Readme

causet

causet (command cst) is a local prototype, built on Git, for experimenting with the source-control ideas discussed in this project:

  • Git remains a real compatibility and storage layer.
  • logical changes keep a stable Change-Id across rebase and cherry-pick;
  • compact merges retain a real causal parent while displaying as one first-parent landing;
  • hard squashes record exactly what they absorbed in a causal landing receipt;
  • a merge planner subtracts proven prior work instead of relying only on Git topology;
  • causal rebase plans and forecasts preview exact omissions, heuristic reviews, replay steps, conflicts, and the predicted tree before a supervised rewrite;
  • supervised causal rebase preserves stable intent, pauses and recovers through a worktree-private journal, and publishes exact mappings only after success;
  • Windows planning and forecasting reuse a worktree-scoped Git object process instead of spawning once per read;
  • reconciliation can be forecast in an isolated worktree and pinned before application;
  • indexed Markdown can be merged deterministically by stable block identity;
  • conflicted reconciliation can pause, survive process exit, continue, or abort safely;
  • exact conflict resolutions can be suggested across branches and worktrees with explicit provenance;
  • workspaces use real Git worktrees but add path-independent logical metadata and non-disruptive checkpoints;
  • Markdown remains canonical while a sidecar gives sections and requirements stable entity IDs.
  • repository metadata can be inventoried, validated, quarantined, and moved between related clones in an integrity-checked Git-bundle envelope.
  • repository and shared-metadata scan costs can be measured in a disposable scale fixture before choosing batching, indexes, or a resident service.

This is a laboratory, not a production VCS. Its purpose is to make the semantics observable and falsifiable before designing a native object store or network protocol.

Documentation map

  • docs indexes the maintained product, architecture, testing, and decision records and explains where transient evidence belongs.
  • Product requirements defines product intent, requirements, success metrics, release gates, the investment themes and native implementation gates, and the trace from every incomplete requirement to the issue that carries it.
  • The project board tracks future work, one issue per increment, in priority order, with the gate each is waiting on. It replaced docs/roadmap.md on 2026-09-04.
  • Architecture maps the current implementation, schemas, runtime flows, safety boundaries, and known debt.
  • Schema catalog publishes one JSON Schema document per persisted and automation-facing record family and maps every --json command to its output contract.
  • Compatibility contract freezes what may change inside a schema version, which versions each family reads and writes, what happens to a version this build does not know, and the resource bound on every record.
  • Human/JSON conformance pins which command output is text, which is JSON, and which members the two renderings must agree on.
  • Logical identity protocol freezes the identifier form, namespace set, and entropy, and states plainly that identifiers coordinate work rather than authenticate it.
  • Canonical JSON profile freezes the byte-exact serialization and hashing rules (an RFC 8785 profile) with shared cross-implementation test vectors.
  • Architecture decisions records constraints that should not be casually reversed; CHANGELOG.md records delivered behavior by version.

Requirements

  • Git 2.40 or newer (the merge-tree forecast engine, the default on Windows, needs Git 2.49 and falls back to the worktree simulator below it)

cst is a native executable, prebuilt for Windows x64 and Linux x64 (glibc). It needs no Node.js.

Install

Linux:

curl -fsSL https://github.com/jwh3times/causet/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/jwh3times/causet/releases/latest/download/install.ps1 | iex

These install the stable release. Every change that lands on main is also released as a GitHub prerelease, and a version becomes the stable release once it passes the whole release gate (see Releases).

Each script downloads the release's archive for your platform, refuses it unless its SHA-256 is the one the release's SHA256SUMS lists, and copies cst into ~/.local/bin (Linux) or %LOCALAPPDATA%\Programs\causet (Windows). It asks for no elevation and changes no PATH; it prints the line to add if the directory is not on it.

  • Read it first, if you prefer. Download the script, read it, then run it: curl -fsSLO <url> and sh install.sh, or irm <url> -OutFile install.ps1 and .\install.ps1. Both are short.
  • Options, which need the downloaded form: --version <x.y.z> installs that release, a prerelease included, and --prefix <dir> installs somewhere else (-Version and -Prefix in PowerShell). The script attached to a release installs that release's layout, so pin both together: https://github.com/jwh3times/causet/releases/download/v<x.y.z>/install.sh.
  • Upgrade by running it again; that also removes the vlab alias an install before v0.23.0 left. Uninstall by deleting the cst file it names when it finishes.
  • Check where a download came from with GitHub's attestation of the release's archives and scripts: gh attestation verify cst-<version>-<target>.tar.gz --repo jwh3times/causet.
  • The archives are on the GitHub release beside SHA256SUMS, to unpack by hand.

With npm

npm install -g --allow-scripts=@holland-vip/causet @holland-vip/causet
cst --help

When CI publishes to npm, @holland-vip/causet@next installs the newest landing's build instead of the stable release. Until an npm bug that blocks it is fixed, npm releases are published by hand.

npm installs the same executable, from a @holland-vip/causet-<platform> package alongside the main one. Nothing is downloaded outside npm and nothing is compiled.

  • --allow-scripts matters on npm 12 and later, which runs no install script it was not told to. The script copies the executable into place so that cst starts it directly. npm 11 and earlier run it without the flag and warn that they do not know it.
  • Without the script cst still works, through a small Node.js launcher that costs Node's startup on every command. cst doctor shows which you have: "launcher": null is the executable, "launcher": "node" is the launcher. Reinstall with the flag to switch.
  • On a platform with no prebuilt executable (anything but Windows x64 and Linux x64 with glibc) the package installs, but cst says so and exits: there is no JavaScript CLI to fall back to since v0.24.0. Build it from a checkout instead (below).

The command is cst. Its old name, vlab, was an alias until v0.23.0 removed it (ADR-0038 §4); a script that still calls vlab must call cst.

Develop from a checkout

A checkout builds cst from native/ with Rust (the toolchain native/rust-toolchain.toml pins) and runs the suites with Node.js 24 or newer; it has no npm dependencies. The build is what the suites run.

npm run build:native
native/target/release/cst --help    # native/target/release/cst.exe on Windows
npm test

Environment variables are named CAUSET_* (for example CAUSET_ENGINE). The former VLAB_* names are ignored: they were read as a fallback until the migration window ended (ADR-0039 §8).

Put native/target/release on PATH to use the build as cst. On Windows, use PowerShell, Git Bash, or a terminal where git, cargo and node are on PATH.

This project now has its own Git history and should live in a normal development repository. The portable repository bundle retains the release commits and tags:

git clone /path/to/causet-<version>.bundle causet
cd causet
git remote remove origin
npm run build:native
npm test

If you instead use the source ZIP, initialize its extracted directory with:

git init -b main
git add .
git commit -m "Bootstrap causet <version>"
npm run build:native
npm test

Five-minute experiment

Create a disposable repository:

mkdir causet-playground
cd causet-playground
cst git init -b main
cst config user.name "Local Tester"
cst config user.email "[email protected]"
cst init

Every command here is cst. cst init, cst commit, cst branch and cst merge are causet's own; cst add, cst switch, cst config and any other command cst does not define run Git with the same arguments, and cst git <arguments> runs Git for any command, the names causet defines included, which is how cst git init creates the repository that cst init then prepares (ADR-0040).

Create a base and a feature with stable change identities:

echo base > app.txt
cst add app.txt
cst commit -m "base"

cst branch feature
echo feature > feature.txt
cst add feature.txt
cst commit -m "feature part one"
echo more >> feature.txt
cst add feature.txt
cst commit -m "feature part two"

cst commit passes --all and --allow-empty through to git commit: --all stages every tracked change first and --allow-empty records a commit whose tree is unchanged. Either way the commit receives its Change-Id trailer.

Recommended compact landing

cst switch main
cst merge feature --compact
cst log --first-parent --oneline
cst show -s --format=%P HEAD

The first-parent log contains one landing unit, while the commit has a real second parent. Stock Git can safely merge the branches later.

cst compact-merge <source> is the same landing as cst merge <source> --compact, and cst hard-squash <source> the same as cst merge <source> --hard-squash; cst merge without a mode flag lands compactly. All three print their causet.landing/v1 receipt as JSON whatever the flags.

Strict hard squash and causal reconciliation

Repeat the experiment with another feature:

cst switch -c hard-feature main
echo first > hard.txt
cst add hard.txt
cst commit -m "hard feature one"
echo second >> hard.txt
cst add hard.txt
cst commit -m "hard feature two"

cst switch main
cst merge hard-feature --hard-squash

cst switch hard-feature
echo continuation > continuation.txt
cst add continuation.txt
cst commit -m "hard feature continuation"

cst switch main
cst merge-plan hard-feature
cst reconcile hard-feature

The planner should report the first two changes as covered by the landing receipt and only the continuation as new. reconcile cherry-picks only the proven-new change and records another causal receipt.

Inspect the ordinary branch graph together with the causal relationships:

cst graph
cst receipts

cst graph deliberately hides internal Git notes and checkpoint refs. Raw git log --all includes the history of refs/notes/causet, which can appear as unrelated commits titled Notes added by 'git notes add'. For a clean stock-Git view, use:

git log --graph --oneline --decorate --branches --tags --remotes

cst receipts is human-readable by default; use cst receipts --json for the complete machine-readable records.

Failure output

Every command's failure has a machine-readable form. Without --json a failure prints cst: <message> on stderr, as it always has. With --json it prints a causet.error/v1 envelope on stdout instead, and leaves stderr empty:

{
  "schema": "causet.error/v1",
  "code": "unknown-schema-version",
  "message": "The reconciliation journal carries unsupported schema \"causet.reconciliation-operation/v99\".",
  "details": "This build reads v4 of that family.",
  "exitCode": 1
}

code comes from a closed vocabulary published in docs/schemas/errors.md, so automation can tell "your build is too old" from "your input is too big" without matching English. Exit codes are unchanged and identical in both modes.

Authorship provenance

cst commit can declare who produced a change, and the declaration survives the rewrites that destroy ordinary Git attribution:

cst commit -m "Add the parser" --generated-by claude-opus-5 --reviewed-by "Jerry Holland"
CAUSET_AGENT=claude-opus-5 cst commit -m "Add the tests"   # an agent harness sets this once
cst provenance HEAD            # or: cst provenance main --all

When actors are declared by flags or CAUSET_AGENT, commit takes the shared notes lock before invoking Git and holds it through provenance publication. A notes-locked refusal leaves HEAD, the index, and worktree content unchanged, including with --all; retry after the holder releases the lock. Commits with no declared actors do not acquire this lock.

Git commit and note publication are still separate writes. If the note write fails after commit creation, the error names the retained commit and reports partial completion. Keep that commit and follow the provenance repair procedure instead of blindly repeating the commit: once the notes write can succeed, cst provenance declare <commit> with the original actors attaches the declaration, and refuses if the commit already has one.

After a hard squash, git blame attributes every absorbed line to the landing commit and the original authorship is gone. The landing receipt already names the absorbed commits, so causet carries their declared provenance onto the landing as the union of their actors, marked carried and naming its sources.

Provenance is declared, never inferred. Nothing examines content to guess who produced it, no existing trailer is read as a role, and a commit with no declaration reports nothing rather than falling back to the Git author. The record is an unauthenticated claim by whoever ran the command, not detection and not proof; signing it is a separate, unimplemented layer (FR-TRUST-02).

The planner uses three statuses:

  • = proven covered by ancestry, stable identity, or a receipt;
  • ? likely patch-equivalent, requiring explicit confirmation;
  • + new work.

Similarity is deliberately advisory. Run cst reconcile <branch> --accept-candidates only after reviewing candidate equivalence.

Proof bundles and the identity audit

A plan's verdict can be handed to another party together with the evidence it rests on:

cst proof-bundle hard-feature > proof.json
cst verify-proof proof.json
cst verify-proof proof.json --offline

cst proof-bundle always prints JSON (causet.proof-bundle/v1): the merge plan with the target commits and change IDs, the reachable accepted receipts and what each absorbs, and the advisory patch-equivalent set, hashed under the canonical JSON profile. cst verify-proof re-derives every classification from that evidence with its own copy of the proof lattice and reports three checks separately: integrity catches editing, classification catches a claim that does not follow from the stated evidence even when the hash was restated, and repository checks evidence, the complete ordered source inventory, commit identities and subjects, counts, lineage, and physical/effective bases against the current repository. Duplicate commits and inconsistent counts also fail offline checks. --offline skips the repository check: success establishes internal consistency, while evidence truth, source completeness, commit identities, and bases remain unchecked; a bundle from an unrelated repository is reported as different-repository. The command exits non-zero when the bundle does not verify.

cst audit identity scans every commit reachable from any ref and every causal record. It reports commits carrying more than one Change-Id trailer, commits sharing a Change-Id with no identity-preserving application record linking them, applied commits with more than one claimed origin, and records that break the identity invariants, and it exits non-zero when it reports errors (--json emits causet.identity-audit/v1). It also warns, without failing, when provenance actor names look like one actor spelled two ways, such as codex and OpenAI Codex; the actor naming convention says how to spell them. A Change-Id is a line of text anyone with repository access can write, so identifiers coordinate work rather than authenticate it and the audit is the defence (docs/identity).

Planning and forecasting a causal rebase

Preview how a linear source branch would be rewritten onto another commit or branch without switching or modifying the caller:

git switch hard-feature
cst rebase-plan main
cst rebase-plan main hard-feature --json
cst rebase-forecast main
cst rebase-forecast main hard-feature --json
git status --short

The plan uses the same exact coverage proofs as reconciliation. Covered changes are marked omit, heuristic patch candidates remain review, and new changes enter the ordered replay queue. It also emits a deterministic fingerprint.

A merge in the range is preserved rather than refused. The rewrite recreates it as a join of its rewritten parents, and the recreated merge claims nothing about the changes beneath it: it takes a new identity recording the merge it came from, carries forward only the resolutions the join needed, and contributes to no coverage class. Coverage keeps coming from the per-change applications alone (ADR-0034). Two shapes are still refused by name, before anything moves: an octopus merge, whose resolution order is not recoverable from its result, and a merge with a parent that is neither in the range nor an ancestor of the new base.

An interactive program is declared, never inherited from Git's sequencer. --reword <commit>, --edit <commit>, --squash <subject>=<target>, and --fixup <subject>=<target> are plan actions, each with its own rule about logical identity (ADR-0035):

  • reword composes the Change-Id trailer itself and refuses a message that would declare a different one — --fork is how you ask for a new identity.
  • squash and fixup leave exactly one trailer on the surviving commit and name the absorbed identities in a record, because several trailers would make the survivor depend on parse order. They differ only in whether the absorbed prose is kept.
  • edit keeps the identity while changing what it contains, so it publishes an amendment. That is the one local operation that can make a proof in another clone wrong, and the amendment is what stops it being silent: a bare Change-Id match for an amended identity degrades from covered to candidate-equivalent. A receipt naming the specific commit still proves that commit, and ancestry still proves what ancestry proves.

reword and edit pause for the caller — cst rebase --continue -m "..." for a message, cst rebase --continue after staging content. An edit is the only action whose result a forecast cannot predict, so a forecast containing one reports pauses-for-content and says it cannot be used as an approval.

rebase-forecast saves a worktree-private causet.rebase-forecast/v3 artifact. It simulates only the ordered replay queue in a disposable detached worktree, records every target-before and result tree, pins the plan fingerprint and candidate policy, and reports a complete predicted tree or a fail-closed conflict/unsupported reason. Dirty caller files are counted but excluded from the committed-head simulation; caller branch, HEAD, index, status, file bytes, and worktree list remain unchanged.

Heuristic candidates still block a final prediction until explicitly accepted:

cst rebase-forecast main hard-feature --accept-candidates

Apply the current named branch after reviewing the plan or a complete forecast:

cst rebase main --use-forecast rebase_forecast_...

Execution rebuilds the plan and rejects a stale forecast before moving the branch. It resets the current branch to the exact onto commit and replays only the selected changes in source order. Clean and contextual same-intent rewrites preserve Change-Id; an unexpectedly empty replay blocks instead of silently disappearing.

If a conflict pauses the queue, ordinary editing and git add remain usable:

cst rebase --status
# resolve and stage files
cst rebase --continue

Use cst rebase --continue --fork when the resolution deliberately changes intent. That creates a new Change ID with Derived-From provenance. Use cst rebase --abort to restore the exact original branch tip, including after earlier queue entries replayed cleanly. Application and summary receipts remain private until the complete queue and any predicted final tree are verified.

Naming an explicit range

By default the source set is everything the branch has that onto does not. --from <base> names the exclusive lower bound instead:

cst rebase-plan main --from HEAD~2
cst rebase-forecast main --from HEAD~2
cst rebase main --from HEAD~2

Without --from nothing changes: the base is the physical merge base and the plan is the one earlier versions produced. With it, only the commits above the base are replayed, and the ones below it are declared rather than dropped — the plan and the summary receipt both list them under excludedByRange with commit, Change-Id, and subject, so you can see exactly what will not travel. No receipt ever claims them; the omission is stated, not proven.

When the base is already reachable from onto, nothing is excluded and the range is an ordinary rebase.

Three ranges are refused with unsupported-range rather than guessed at: a base that is not an ancestor of the tip, a base that is the tip, and a tip that is not a branch tip. The last is the one worth knowing — the commits after a mid-branch tip would need new parents, which is interactive editing rather than a linear range.

A forecast pins the range base, so an approval for one range refuses to authorize another with stale-forecast. Abort is unaffected: the range decides what is replayed, never what is restored. See ADR-0032.

Carrying your own uncommitted work through the rebase

A rebase rewrites the branch you are standing on, so the draft in that worktree is normally in the way: cst rebase refuses a dirty worktree. --target-checkpoint on the forecast carries it instead:

cst workspace checkpoint --label "mid-refactor"
cst rebase-forecast main --target-checkpoint
cst rebase main --use-forecast <id>

This is the same overlay contract the reconciliation side uses, applied to the rebase journal, so carrying the target's own uncommitted work is the full description and nothing about it differs here. Two details are specific to a rebase. The re-materialization merges the draft onto the rewritten tip, with the tree the branch held before the rebase as the base, and that prediction is pinned once per run rather than once per pick. And the merge is what keeps the new base: writing the checkpoint's tree back would restore the pre-rebase content of every file the new base changed, silently undoing what you rebased onto.

The worktree must be a registered workspace, because a checkpoint belongs to one. Everything else is unchanged — a drifted worktree refuses with stale-overlay before anything moves, no receipt mentions the draft, and abort restores the original tip first and the captured worktree second.

Linear rebase operates only on the current named branch. Merge-preserving and interactive edit/reword/squash rebases remain ordinary Git workflows.

Forecasting reconciliation

The lab can simulate the complete proven-new queue before touching the current worktree:

cst forecast feature
git status --short

The command creates a disposable detached Git worktree, applies clean changes, uses any single exact-resolution candidates in the simulation, and removes the temporary worktree. It reports each predicted causal decision, the partial or complete result tree, blocking conflicts, and forecast duration. The caller's HEAD, index, and working files are checked before and after and must be unchanged.

With the merge-tree engine (--forecast-engine merge-tree or CAUSET_FORECAST_ENGINE=merge-tree; the default on Windows) clean steps are simulated instead through one persistent git merge-tree process with no temporary worktree, pinning the same per-step and predicted trees. Any conflicted, empty, or otherwise unsupported step hands the whole forecast back to the worktree simulator, and the forecast reports which engine produced it and every fallback reason. The engine needs Git 2.49, the first version whose git merge-tree --stdin flushes each answer before reading the next request; on older Git the session process reports its version as it starts and the forecast records a git-too-old fallback without waiting or spawning another process. The worktree simulator remains the oracle and the default on POSIX hosts, where distribution Git is often older than 2.49; --forecast-engine worktree selects it anywhere.

Each forecast is pinned to exact source and target heads and a fingerprint of the causal merge plan. After reviewing it, explicitly authorize its exact resolution IDs as a batch:

cst reconcile feature --use-forecast forecast_...

Heuristic patch-equivalence remains a separate trust decision. A forecast with unaccepted ? candidates reports review-required and does not claim a final tree; review them and regenerate with --accept-candidates if appropriate.

Application rechecks every conflict signature and resolution ID. If branch or causal metadata changed, the command stops before starting. A complete forecast also pins the predicted result tree; a mismatch prevents receipt publication and can be safely rolled back with cst reconcile --abort.

Forecasts operate on committed heads. Dirty files are left untouched and their count is reported rather than silently included. Run the prepared experiment with:

npm run demo:forecast

Resumable conflict reconciliation

When a proven-new change conflicts, cst reconcile leaves a durable operation in the current worktree instead of losing causal context:

cst reconcile feature
cst reconcile --status

# Resolve and stage conflicted files.
git add <resolved-files>
cst reconcile --continue

The completed application receipt links the source commit and Change ID to the context-specific result commit and records the conflicted paths. If the resolution changes the logical intent rather than adapting it to the target context, fork the identity explicitly:

cst reconcile --continue --fork

Abort restores the exact target commit from which the complete reconciliation began, including when earlier changes in the queue applied cleanly:

cst reconcile --abort

Pending state is stored under the current worktree's private Git directory. Two agents can therefore pause independent reconciliations in separate worktrees without overwriting each other's operation state. Completed receipts remain shared repository metadata.

Run the prepared conflict experiment with:

npm run demo:conflict

Reusing an exact conflict resolution

Each conflict is recorded under an exact signature of the ordered base, target, and source blobs involved. The signature excludes the path, so a prior resolution can be found on another branch or in another linked worktree when all three inputs are identical.

When reconciliation pauses, inspect any matches:

cst resolve status

No suggestion is applied automatically. Choose one explicitly, inspect the staged result, and continue:

cst resolve apply shared.txt
git diff --cached -- shared.txt
cst reconcile --continue

For several unambiguous conflicts, use cst resolve apply --all. If the same signature has more than one known result, select one with --resolution <id>. To decline prior results while keeping the decision in the receipt, run:

cst resolve reject shared.txt
# Resolve shared.txt manually, then:
git add shared.txt
cst reconcile --continue

The application receipt distinguishes created, accepted, modified, and rejected outcomes. cst resolve list shows the repository-shared catalog. An exact result is still never selected implicitly: it is batch-applied only when --use-forecast names the reviewed, pinned forecast. Run the prepared two-conflict experiment, whose second occurrence is in a linked worktree, with:

npm run demo:resolution

AI-oriented workspaces

cst workspace create agent-auth --from main --owner agent-7 --focus service:auth
cst workspace list
cd ../causet-playground.workspaces/agent-auth
echo draft > agent-plan.md
cst workspace checkpoint --label "agent handoff"

--owner and --focus are free-text labels recorded on the workspace descriptor. On a large tree, --cone <dir,dir> materializes only the named directory prefixes through Git's cone-mode sparse checkout: the workspace ID, compatibility branch, pinned base, checkpoints, and lifecycle are the same with or without it, a checkpoint still captures the full tree, restore reapplies the cone, and git sparse-checkout disable inside the worktree reverses it. Cone paths must be relative and inside the repository.

From the original or another linked worktree, move or temporarily dematerialize a workspace without changing its identity:

cst workspace move agent-auth ../causet-playground.workspaces/agent-auth-2
cst workspace archive agent-auth
cst workspace restore agent-auth --path ../causet-playground.workspaces/agent-auth-3
cst workspace repair agent-auth --path ../causet-playground.workspaces/agent-auth-3
cst workspace prune --dry-run

Archive refuses tracked or untracked changes, ignored files, and unfinished reconciliation or rebase journals, even when the worktree is clean. A journal's presence produces operation-in-progress; malformed and newer-version journals are preserved too. In that workspace, inspect cst reconcile --status or cst rebase --status, then continue a resolved conflict or abort the operation. Clean interrupted publication and forecast mismatches require abort before retrying. If this build cannot read a journal, preserve it and recover with the writing build.

Prune previews missing registry paths and only changes them with --apply. Because Git pruning acts across the repository, an applying prune with candidates refuses while any linked worktree has either journal, including unregistered or currently materialized worktrees. Restore missing paths and repair their Git links before recovering those operations. Move and repair preserve private journals and recovery state. Branch and checkpoint refs remain available while a workspace is archived.

Create, move, archive, restore, repair, and prune with --apply serialize their registry reads, Git operations, and registry writes on <common-git-dir>/vcs-lab/workspaces.lock. Contenders wait up to five seconds and then refuse with workspace-registry-locked; listing and prune previews remain available. A crashed holder leaves its lock in place. To recover, stop workspace writers on every host sharing the repository, inspect the registry and git worktree list for partial changes, then remove only workspaces.lock before restarting writers. The tool never steals a lock based on its age, an unreadable claim, or a missing PID.

A materialization failure leaves the registry unchanged and preserves any partially created worktree or branch for inspection. Repair or remove that partial materialization deliberately with Git before retrying. The registry lock does not make Git mutations and registry publication one atomic operation.

Compare two workspace branches without disturbing either worktree:

cst workspace forecast agent-auth agent-payments
cst workspace forecast agent-auth agent-payments --source-checkpoint
cst workspace forecast agent-auth agent-payments --target-checkpoint
cst workspace forecast agent-auth agent-payments --source-checkpoint --target-checkpoint

The ordering is target <= source: this previews applying the committed head of agent-payments onto agent-auth. With --source-checkpoint, the source is the latest immutable checkpoint whose base still matches the source head. Live dirty bytes after that checkpoint remain excluded. The target is its committed head unless --target-checkpoint is given, as described below. The two options combine, and the forecast then reports the scope source-and-target-checkpoint, which is what its approval covers. The forecast is stored privately in the target worktree, where its printed reconciliation command should be run.

Carrying the target's own uncommitted work

--target-checkpoint carries the target's draft through the application and puts it back afterwards. It is available on cst forecast too, with identical semantics, and on cst rebase-forecast, where the overlaid worktree is the branch being rewritten.

An overlay is uncommitted context, never a committed draft. It changes no coverage decision: the plan, its fingerprint, and the committed predicted tree are exactly what they would be without it, and no receipt mentions it. What the forecast adds is a second prediction — the worktree after the draft is put back — which the application verifies before publishing anything.

Nothing is ever captured for you. Uncommitted work with no checkpoint is refused, because an overlay is state you approved. Once approved, the live tree must still match the checkpoint exactly; if you kept typing, the run refuses with stale-overlay before touching anything, and the remedy is a new checkpoint. Your newer work is left exactly where it is.

Applying reduces the worktree to the committed head, replays the changes, and then re-materializes the draft by merging it onto the result — not by writing the checkpoint's tree back, which would undo the very changes that were just applied. If the re-materialized tree does not match the prediction, nothing is published and abort is the recovery. Abort restores the committed tip first and unconditionally, then the captured worktree including its untracked files; an overlay it cannot read is reported as unrecoverable rather than guessed at. See ADR-0028.

The checkpoint captures tracked, modified, and untracked non-ignored files in an immutable Git commit referenced under refs/causet/checkpoints/.... When a new checkpoint replaces it, a history ref retains the previous checkpoint. The operation does not alter HEAD, the index, or the working directory.

This approximates the proposed distinction:

  • Workspace: pinned base, private draft state, ownership/focus metadata, and checkpoint history.
  • Worktree: one ordinary filesystem materialization of that workspace.

The prototype still creates a causet/ws/<name> compatibility branch because Git requires one to retain normal linked-worktree behavior. A native implementation would use a workspace ref and private draft stack instead.

Annotated Markdown

Create a specification:

# Checkout

REQ-CHECKOUT-1: Order submission must be idempotent.

## Failure behavior

Return a typed error when authorization fails.

Then index it:

cst spec index docs/checkout.md
cst spec show docs/checkout.md

The exact Markdown remains canonical. The tracked .causet/specs/docs/checkout.md.json sidecar assigns stable IDs to the preamble, headings, and explicit REQ-*: entries. Manifests are sparse and deterministic: titles, positions, content hashes, and ordinary IDs are derived from Markdown rather than duplicated. The sidecar retains artifact/source identity, entity count, an optional Git blob identity, and only exceptional legacy ID overrides.

The v4 writer excludes headings and REQ-*: declarations inside supported backtick and tilde fences. Historical v1/v2/v3 manifests retain their old view until cst spec index migrates them, preserving verified real entity IDs. Indexing refuses migration if the original source cannot be recovered. The fence and migration contract specifies the supported syntax and recovery.

Migrate and commit the common baseline before starting new branches. If an existing merge's legacy base has affected boundaries, migrating only the tips is insufficient: review an ordinary Git merge and reindex its result. Old semantic forecasts must be regenerated; pending operations with old semantic decisions must be aborted and restarted.

An unchanged source hash is an incremental-index cache hit and does not rewrite the sidecar. Repository-wide indexing additionally compares tracked Git blob IDs first; unchanged documents are neither opened nor hashed. Index every tracked or non-ignored Markdown document in one pass:

cst spec index --all

--force, on either form, re-parses the Markdown and re-derives the manifest even when the tracked blob or source hash reports it unchanged, which is how a sidecar is refreshed deliberately.

Deterministic block reconciliation

Heading-delimited sections are the disjoint merge units. REQ-* records remain independently addressable entities, but their text is merged as part of the containing section so overlapping units cannot produce inconsistent bytes.

The three-way merge is deliberately conservative:

  • edits to different blocks combine;
  • a block move on one side combines with a content edit on the other;
  • identical concurrent edits or additions combine;
  • same-block divergent edits remain blocked;
  • delete-versus-edit and incompatible ordering remain blocked.

The result is rendered with LF endings, one blank line between blocks, and one final newline. No language model judgment is involved. The normal forecast automatically discovers these decisions, records their exact input signature and result hashes, and can apply them only through the reviewed forecast:

cst forecast feature
cst reconcile feature --use-forecast forecast_...

To inspect the semantic merge independently of reconciliation:

cst spec merge-plan docs/checkout.md <base> <target> <source>

Without a forecast, reconciliation pauses before changing conflicted spec bytes. Inspect and explicitly stage a clean deterministic suggestion:

cst spec status
cst spec resolve --all
git diff --cached -- docs/checkout.md .causet/specs/docs/checkout.md.json
cst reconcile --continue

If you edit the staged suggestion, re-run cst spec index, stage both the Markdown and sidecar, and continue. The application receipt records the semantic decision as accepted or modified; a stale sidecar cannot be committed through reconciliation.

Run the prepared experiment with:

npm run demo:spec

Commands

Run cst --help for the current command list. The most useful commands are:

| Command | Experiment | | --- | --- | | cst commit | Stable logical change identity | | cst merge --compact | First-parent compression without causal loss | | cst merge --hard-squash | Git-compatible strict squash plus sideband receipt | | cst compact-merge, cst hard-squash | The same two landings as standalone commands | | cst merge-plan | Proven coverage versus heuristic similarity | | cst proof-bundle, cst verify-proof | Portable coverage evidence and its independent verification | | cst rebase-plan | Read-only causal omission/review/replay planning for a linear rebase | | cst rebase-forecast | Non-mutating simulation and private pinning of a causal rebase plan | | cst rebase | Supervised current-branch replay with stale checks, continue/fork/abort recovery, and completed receipts | | cst forecast | Non-mutating reconciliation simulation and pinned approval | | cst reconcile | Apply only proven-new changes with resumable conflicts | | cst resolve ... | Inspect, apply, reject, and audit exact resolution suggestions | | cst cherry-pick | Preserve or deliberately fork a Change ID; a change the target already covers is a no-op unless --repeat is given | | cst graph | Branch history plus causal relationships, without metadata-ref noise | | cst workspace ... | Worktree-backed lifecycle, checkpoints, and committed/checkpoint forecasts | | cst spec ... | Incremental indexing, block merge planning, explicit resolution, and corpus benchmarks | | cst receipts | Inspect causal records as text or JSON | | cst provenance | Read declared authorship provenance, carried across rewrites; cst provenance declare declares it for an existing commit | | cst audit identity | Repository-wide Change-ID collision and duplicate-origin audit | | cst metadata ... | Inventory, validate, transfer, and benchmark accepted metadata facts and scan paths | | cst doctor --benchmark | Sample ordinary Git latency and persistent object-session reuse | | cst fetch, cst pull, cst push, cst clone | Git's commands, carrying the causal records with them (see Records over Git remotes) | | cst git <arguments> | Run Git for any command, including the names cst defines (cst git commit --amend) |

Every other command is Git's (ADR-0040): cst status, cst log, cst add, cst switch and the rest run git with the same arguments, the same terminal, and Git's exit status, so cst is the only command a session needs. On Unix cst becomes the git process; on Windows it runs git and waits. A flag after a passed-through command is Git's, so --json and --engine there mean what Git makes of them.

Experimental: native repositories (N1, ADR-0045). With CAUSET_EXPERIMENTAL=native set, cst import <git-repo> <dest> copies every object a Git repository's refs reach into a new native repository, and records every ref in a snapshot: a directory holding .cst/, in the format of the native store contract. Commits and tags are kept in Git's encoding, byte for byte, and each commit a branch, a tag or a remote-tracking ref reaches also becomes a native commit (native history, ADR-0047); a commit only other refs reach, such as the notes' history, does not. A new version of a file of 1 MiB or more may be stored as a zstd delta against the file's previous version, when that is smaller than its chunks. Importing the same history again writes the same bytes. Importing into an existing native repository adds only what it does not hold, with the native commits its history still lacks, then replaces its snapshot. A shallow clone, a partial clone, or a repository with grafts is refused, since Git reads its history differently from what it stores, and so is one with a ref, or another worktree's HEAD, naming an object it does not hold: import names the first such ref and writes nothing. So is one with a symbolic ref whose name is not UTF-8: Git cannot be given that name to say which ref it points to. So is one whose refs reach a commit Git's log cannot read either: one whose first line names no tree, or whose tree or a parent is an object of the wrong type. In a native repository, cst cat-file (-p | -t | -s) <object>, cst ls-tree, cst rev-parse and cst for-each-ref --format print what Git prints on the original, with native IDs in place of Git's, and run no Git. They name a commit by its native commit, and take that ID, a unique prefix of it, or the commit's Git ID; cst rev-parse --git-id prints the Git ID of what each revision names. cst cat-file shows a native commit as the Git commit it was imported from: type commit, Git's bytes, and with -p its tree and parents named by their native IDs. A commit with no native commit, such as one only the notes' history reaches, keeps the ID of its preserved Git object (native history). cst cat-file --batch and --batch-check [--buffer] answer each object named on standard input from one opened store, in Git's default formats: the header names the native ID, and --batch's content is the object's Git bytes, Git IDs included, the size cst cat-file -s gives. Each takes the part of Git's command implemented so far, listed by cst --help there, and refuses the rest by name. cst log [<revision>] --format=<format> prints the history of a revision, HEAD by default, in Git's order, as git log --format prints it, for the placeholders cst --help lists there. It reads native commits alone, so %H and %P name native commits, and every %h it prints resolves in the other commands. A native repository imported before native commits existed has none until it is imported into again: cst log refuses it, and the other commands name its commits by their preserved Git objects. cst fsck verifies the store: every copy of every object in every container, and content absent by promise or by policy, which it reports by state rather than as corruption. It also checks each native commit by the rules of native history, deriving an imported one again from its Git commit. cst import --verify [<native-repo>] rebuilds every imported object in Git's encoding from the store alone and checks that it hashes to its original Git ID, also without Git. Those two, cst cat-file --batch and --batch-check, and an import into an existing native repository, read the alias files and every container's index whole: a batch names many objects, so it pays for the store's size once rather than for a read per lookup. cst log reads every container's index and every native commit, once per command. The other reads above check only the parts of the store they touch and verify each object they read by its ID, so their cost does not grow with the store's object count, except where they name a commit: finding the native commit import stored straight after a commit's preserved object reads every container's index whole, once per command, and a commit with none, such as a carrier, costs a read of every native commit too. A read that misses, or resolves an abbreviation, first reads the files it searched whole, once per command, so damage is reported rather than answered as a missing object (storage.md §4.1). Every other command in a native repository is refused, because it has no Git to pass it to (ADR-0046). None of this is a contract yet: the format and the output may change, and a native repository may have to be imported again.

A command cst defines refuses an option it does not take with usage-unknown-option rather than ignoring it; for init, commit, branch, merge, rebase and cherry-pick the refusal names cst git and the command, for Git's own form.

For ordinary Git commits without a Change-Id, cst cherry-pick recognizes exact target ancestry and validated, reachable identity-preserving application records. A covered pick returns a no-op without starting Git's sequencer; --repeat explicitly reapplies it. Forks and patch similarity alone do not establish coverage for the original change.

Metadata integrity and portability

Inspect every metadata scope without changing the repository:

cst metadata status
cst metadata validate --json
cst metadata validate --strict

The inventory covers causal note attachments and record schemas, referenced commits/trees/blobs, exact-resolution signatures and retention refs, tracked spec/source consistency, workspace/checkpoint health, and counts of worktree-private operations and forecasts. JSON diagnostics use stable codes. Unknown, malformed, dangling, signature-mismatched, or ID-conflicting records remain inspectable but cannot prove coverage, appear as exact resolutions, or enter an export. Strict validation additionally fails on warnings such as a missing workspace path or active private operation.

Newly published facts retain their required commits, trees, and blobs under refs/causet/retention, so deleting a rewritten source branch and running Git GC does not invalidate its receipts. Retention is monotonic: aborting an operation or deleting a note does not release objects. Retained receipts still prove coverage only when their attachments are reachable from the selected target. See ADR-0025.

An ordinary clone fetches branch refs, not causal notes or their shared causet refs. A clone that fetches refs/notes/causet without refs/causet/retention can therefore see a valid record but not the retention carrier that keeps its attachment readable; metadata validate then reports missing-attachment even though the origin is healthy. Fetch the refs as shown under Metadata locations before interpreting validation from a low-level same-origin read.

Records over Git remotes

cst fetch, cst pull, cst push and cst clone take Git's arguments, run Git's command, and carry the records with it (ADR-0040), so a clone that only ever uses cst never needs a refspec:

cst clone https://example.test/project.git   # git clone, cst init, then the records
cst pull                                       # git pull, then the records
cst push -u origin feature                     # the records first, then git push
  • What moves: refs/notes/causet, refs/causet/retention and refs/causet/resolutions/*, each by name. Checkpoints, parked conflicts and every other refs/causet/* ref stay in the clone.
  • Fetching stages the remote's records under refs/causet-remote/<remote>/, then brings them in exactly as cst metadata import --apply --park-conflicts brings in an envelope: every record is validated, an unreadable one is excluded, and a record whose id names different content here is parked rather than overwriting anything (ADR-0030). The remote's notes and retention commits become parents of this clone's, so the next push is a fast-forward.
  • Pushing sends the records first, in one atomic push that is never forced, and only then runs git push with your arguments, so a branch never reaches the remote before the records about it. If the remote's records moved since your last fetch, cst push fetches and merges them and tries again. While a parked conflict has no disposition, cst push refuses before anything moves: pushing would replace the remote's copy without a decision. Run cst metadata dispose, or push without the records. Your pre-push hook runs once, on Git's push of your refs; the records push skips client hooks.
  • --no-records runs Git's command alone. --json prints a report of the records moved (cst fetch, cst push and cst clone; cst pull prints Git's merge output on standard output and has no JSON form).
  • cst push --mirror is refused, because it would push the clone's local refs too; cst git push --mirror is Git's own. A plain git fetch or git push still carries no records.

For notes created by an older version, preview and apply an explicit backfill:

cst metadata retain --dry-run --json
cst metadata retain --apply --json

Backfill retains still-valid facts and reports quarantined records, including already missing objects. It cannot restore missing history. A partial backfill with quarantined records returns exit status 1; repeating an unchanged backfill does not move any refs.

Create an offline envelope, clone the ordinary project content, preview the exact destination actions, then apply them:

cst metadata export ../project-metadata
git clone /path/to/project ../project-copy
cd ../project-copy
cst metadata import ../project-metadata --dry-run
cst metadata import ../project-metadata --apply

An envelope directory contains manifest.json and, when portable facts exist, objects.bundle. Export is deterministic for fixed accepted facts. It carries sanitized refs/notes/causet data, the commit history required by accepted causal records (including rewritten rebase origins), and accepted refs/causet/resolutions/* commits/blobs, including independent conflict-stage blobs. The envelope builds a carrier for its accepted facts and excludes the local retention chain. Tracked spec manifests already move with ordinary Git content. Workspace registries, checkpoint refs, active reconciliation/rebase journals, and saved forecasts are excluded.

Import requires the same Git object format and at least one shared root commit, which supports ordinary clones and forks while unrelated and history-filtered histories fail closed in envelope v1. Dry-run verifies the manifest, bundle, records, refs, and required content objects without changing destination refs. Apply uses staging refs and one checked ref transaction; repeated import is a no-op, and a conflicting record ID or resolution ref is never overwritten.

These checks establish internal integrity, not cryptographic signature trust, actor identity, landing authorization, or permission to execute content.

Competing facts: parking and disposition

A conflict is one record identifier naming different content — nothing else. Two records with distinct identifiers are independent facts even when they claim the same thing, so an ordinary re-run that writes a second receipt onto one commit is not a conflict.

While a conflict is unresolved, neither copy is used: it proves no coverage, serves as no resolution candidate, shows no provenance, and is not exported. The change it would have covered is classified from the evidence that remains, so it moves to candidate-equivalent or new and never the other way, and the plan, the forecast, and the receipt carry a quarantinedFacts list naming what was excluded. Nothing blocks: one disputed record from one peer must never stop local work.

The default import still refuses a whole envelope over one conflict. Park mode applies the rest instead and sets the conflict aside:

cst metadata import ../project-metadata --apply --park-conflicts

Each conflicting incoming record becomes the blob of one ref under refs/causet/quarantine/<source-lineage>/<record-id>, inspectable with git cat-file -p, listed by cst metadata status beside the local digests it disputes, and excluded from every reader and from export. The namespace is local: nothing fetches or pushes it.

A successful park exits 0, and the report names what was parked. Park mode exists so one disputed record cannot stop an exchange, so it does not signal failure for having done its job; read summary.parkRecords and the parked list, or cst metadata status, to act on a dispute.

A person then decides, once:

cst metadata dispose <record-id> --keep-local --reason "the peer altered it"
cst metadata dispose <record-id> --replace-local

--keep-local removes the parked copy and returns the local record to service. --replace-local rewrites the local record to the parked content under the notes lock and returns that instead. Either way the decision is recorded in <common-git-dir>/vcs-lab/dispositions.json with the digest kept and the digests rejected, so the same disagreement arriving again is reported as already disposed rather than parked a second time. That registry is deliberately local: two clones may decide differently, and the disagreement between them is real.

Git's own git notes merge is not a supported way to combine causal notes on either side of this: the manual strategy stops in a conflicted worktree, and -s union concatenates the containers into something causet reads as malformed, dropping every record on that attachment. See ADR-0030.

Verifying a plan without the repository

cst proof-bundle <source> emits a causet.proof-bundle/v2 document and cst verify-proof <file> checks it. The bundle carries the classification, the evidence it was derived from, and — since v2 — Git's own bindings for what it claims: the raw commit objects of the source range, a commit path from the target head for every covered change, an inclusion proof from the notes tip to each receipt it relies on, and the anchors those proofs terminate at.

cst proof-bundle feature > proof.json
cst verify-proof proof.json --offline
cst verify-proof proof.json --offline --anchors-from https://github.com/you/project.git

The verifier recomputes every carried object's id from its bytes. That is the whole mechanism: a sender chooses what to put in a bundle, but it cannot choose the id of a commit whose message it altered. So a bundle that omits a change, injects a commit from an unrelated repository, substitutes a foreign commit id, or borrows a Change-Id fails offline — even after the forger recomputes the bundle hash, which before v2 was enough to pass.

A conclusion is reported at one of three tiers, and they are different statements rather than degrees of confidence:

| Tier | What it says | | --- | --- | | self-consistent | the classification follows from the evidence the bundle states | | bound | that evidence is tied to Git objects, between the heads the bundle states | | anchored | those heads are the real ones, confirmed from a channel you chose |

--anchors-from <remote> is that channel: it reads git ls-remote from a remote you name. A remote named inside the bundle is only a hint, because the bundle's producer controls it. Root commits are not ref tips, so that channel cannot confirm them and the report says so instead of pretending otherwise.

What stays out of reach without the repository is absence. That a change is genuinely new is a claim about the whole target history, and candidate-equivalent is a claim about trees, which the bundle deliberately does not carry. Both are reported as claimed, never proven, and ok never asserts a conclusion the carried material cannot support; the report lists each one with its reason. Running verify-proof inside the repository still adds the comparison that catches fabricated evidence, and it is the only check that establishes absence.

A v1 bundle from an older producer still verifies, at the self-consistent tier only. See ADR-0031.

What this build can exchange

Two builds decide what they may exchange by comparing documents, not by asking a server. cst capabilities prints what this build reads and writes, projected from the same registries the rest of the tool enforces, so the statement cannot drift from the behavior:

cst capabilities
cst capabilities --json

Outside a repository the document is build-scoped; inside one it adds the object format and lineage, which makes it repository-scoped. It writes nothing.

Negotiation is a pure function of two such documents, so every conclusion a gateway would enable is already available offline:

cst capabilities --against ../peer-capabilities.json
cst capabilities --against ../project-metadata      # an envelope directory

The report separates an exchange that is smaller from one that is impossible. A version gap in a family is smaller: a stored record's version is fixed by whoever wrote it and is never re-encoded, so records the peer cannot read are filtered out and named, together with what the peer's own document says it would do with them, and everything else still moves. The command exits non-zero so a script notices, while the exchange remains possible.

A disagreement about a profile, an algorithm, the object format, or the lineage is impossible: there is no set of bytes both sides would read the same way, so it refuses with no-common-version, or repository-mismatch for the repository cases, before anything is transferred. A feature token a reader does not know is opaque and is ignored rather than refused, and bounds are the receiver's — a record over the peer's advertised bound is withheld and reported rather than sent to be refused.

An envelope manifest states a producer, a repository, and feature tokens and nothing else, so negotiating against one reports the families as not stated rather than as unreadable. That distinction is the point: a document says what it says, and a report that filled in the rest would be inventing a peer.

The gateway itself is not built. It would add exactly one thing an offline reader cannot have — the current document of a party that is not in the room — and would change nothing about what negotiation concludes. See ADR-0033.

Metadata locations

  • Git notes: refs/notes/causet
  • Required objects of published facts: refs/causet/retention
  • Pending reconciliation: the current worktree Git directory under causet/reconciliation.json
  • Pending causal rebase: the current worktree Git directory under causet/rebase.json
  • Saved forecasts: the current worktree Git directory under causet/forecasts/<forecast-id>.json
  • Workspace registry: the common Git directory under causet/workspaces.json
  • Checkpoints: refs/causet/checkpoints/<workspace-id>
  • Parked conflicting records: refs/causet/quarantine/<source-lineage>/<record-id>
  • Conflict dispositions: the common Git directory under causet/dispositions.json
  • Reusable resolution blobs: refs/causet/resolutions/<signature>/<result-blob>
  • Portable spec manifests: .causet/specs/**/*.json

Repositories from before causet

These are the only locations cst reads. A repository holding metadata from a build before causet keeps it under refs/notes/vcs-lab, refs/vcs-lab/*, <git dir>/vcs-lab/ and .vcs-lab/specs/, and has to be moved once. Until it is, every command except cst migrate, cst doctor and cst --version refuses it with the error unmigrated-repository, and cst doctor reports migration: unmigrated (ADR-0039 §3, §8):

cst migrate --dry-run   # every ref, setting, path and manifest it would move; changes nothing
cst migrate             # creates the new refs, repoints the notes settings, moves the runtime directories
git commit -m "Move specification manifests to .causet/specs"   # the manifest move is staged, never committed for you

cst migrate refuses while a reconciliation, rebase, export or import is in progress, and never deletes anything: the former refs stay where they were. An operation that a build before causet 0.22 left pending in an unmigrated repository has to be finished or aborted with that build first, because this one will not act there. A former ref that moves afterwards (a peer on an older build published to it) is reported as legacy-ref-advanced; running cst migrate again fast-forwards the new ref, and refuses if both moved. Records keep their vcs-lab.* identifiers forever and are read as the causet.* families they name. Existing vlab/ws/<name> workspace branches keep their names; new workspaces use causet/ws/<name>.

cst fetch and cst push carry these refs for you (Records over Git remotes), and cst metadata export/import moves them as a file. For a low-level same-origin read with Git alone, fetch the notes, the retention root and the resolution refs together, each by name:

git fetch origin 'refs/notes/causet:refs/notes/causet' \
  'refs/causet/retention:refs/causet/retention' \
  'refs/causet/resolutions/*:refs/causet/resolutions/*'

Name them; a refs/causet/* glob also copies the publisher's checkpoint refs and parked conflicts (refs/causet/checkpoints/**, refs/causet/quarantine/**), which belong to that clone alone.

A publ