Skip to content

Release semantics ​

The semantics below are load-bearing — they are pinned by ADR-0003 in the org ledger (9aia/project, project/adrs/0003-tarsi-release-semantics-plan-dry-run-bump-tag-manifest.md). This page is the readable summary; the ADR is the contract.

Dry-run is the default ​

tarsi-serve release mutates only with dry_run: false — the --yes equivalent. Orchestration callers (peregrin campaigns, agents) opt in explicitly; anything probing a repo gets plans, never writes. This mirrors the org rule that service surfaces never mutate unless asked.

Bump inference ​

Conventional commits, attributed to units by path prefix. The inference itself is a strategy (P-030) — data-driven rules in tarsi.toml's [release] strategy, defaulting to conventional:

commitbump
featminor
fix / perfpatch
! / BREAKING CHANGE:major
chore / docs / test / …none — no release

Bump rules fold max-match (a commit contributes the highest matching bump; the unit folds max across commits) against the commit's raw type token — arbitrary types like deps are nameable. Changelog sectioning is the same mechanism: ordered sections[], first match wins, table order = render order. semantic-release-angular ships semantic-release's commit-analyzer angular preset as data; keep-a-changelog keeps the same bump rules but renders the six canonical keepachangelog.com sections (### Added/Changed/Deprecated/Removed/Fixed/Security) — KaC is a changelog layout, not a bump policy. Custom tables cover anything else short of non-semver versioning or plugin execution (the documented P-030 boundary).

spec.bump (unit override or explicit unit spec) wins over inference; the strategy's fallback — filled by release.default_bump when unset — is the repo-wide fallback when inference finds nothing. Commits with empty path lists match every unit — conservative attribution. release.diff_exclude strips matching paths before attribution (a commit left with no paths is dropped).

Per-unit tags, per-unit ranges ​

Tag format is {unit}-v{version} per unit (tamias-core-v0.4.2), not repo-level v{semver}. Each unit's commit range is {latest-tag-for-that-unit}..HEAD — units release independently and only when their own paths changed. params.range overrides with one range for all units.

Manifest mutation ​

Versions are written via toml_edit (tarsi-manifest) — formatting and comments survive. Units with version.workspace = true bump [workspace.package].version instead: all releasing units in such a workspace share one bump (last-writer-wins today; per-unit workspace versions are a known limitation).

Ordering and rollback ​

The mutation phase is strictly ordered — changelogs → manifests → scoped git add (never -A) → chore(release): bump versions commit → per-unit tags → push branch and tags → publish. The push-before-publish order is load-bearing: GitHub Releases auto-creates refs/tags/<tag> at remote HEAD when the tag doesn't exist yet, which would pin the release to the pre-bump commit.

Failure handling:

  • Any mutation failure → rollback undoes exactly what ran (remote tags deleted, branch reset, local commit/tags removed, created changelog files deleted) and the op reports rolled_back.
  • Publish failures roll back only if nothing published — once a target succeeded, deleting the tag would orphan a live release, so state is left and the report asks for manual cleanup.

The LLM boundary ​

There is deliberately no tarsi-llm. Changelog polish composes with sepia: the caller (peregrin node, agent) may prompt a sepia session with the rendered changelog. Conventional-commit output is the only in-repo path — deterministic by construction (ADR-0003, decision 6).

Secrets ​

Config carries env-var names (token_env, CARGO_REGISTRY_TOKEN via cuora secrets records) — never values. The cuora boundary holds end to end: names in manifests, values in the secrets broker.

VCS ownership ​

Git history, tags, and push go through lasius-vcs + lasius-vcs-git (org plan P-019). tarsi-core is pure — it sees only Commit values; every VCS call lives in tarsi-serve (and tarsi-testkit fixtures). New publish targets are a new tarsi-publish-* crate plus a PublishTarget variant; serve dispatch stays a match arm.

MIT licensed — part of the 9aia GAIA stack.