ORSet.compact() returns CompactionReceipt #474

1. Background Context

Source: git-warp #474. Audited against main 94b40dac64034cd8caab9bb05efe14a0c22bd735. Template: feature; work type: type:feature.

Current scope and disposition: A supported compaction receipt must wait for safe membership-retirement semantics. Diagnostic counting that retains evidence can be a narrower independent card, but is not the current compact-and-remove proposal.

Discussion evidence, including corrections:

• Comment ABYi6DXA

2. Problem Description

A supported compaction receipt must wait for safe membership-retirement semantics. Diagnostic counting that retains evidence can be a narrower independent card, but is not the current compact-and-remove proposal.

Historical source report; the current disposition above supersedes obsolete claims:
ORSet.compact(includedVV) currently mutates the set in place and
returns nothing. The caller has to diff before/after metrics manually
(GCPolicy does this with collectGCMetrics).

Instead: compact() returns a CompactionReceipt — a frozen value
object with { dotsRemoved: number, elementsRemoved: number }. The
caller gets structured feedback without manual diffing.

const receipt = state.nodeAlive.compact(appliedVV);
logger.info(`GC: removed ${receipt.dotsRemoved} dots`);

This aligns with the Systems-Style manifesto: structured data stays
structured (no "count before, count after, subtract" pattern).

2b. Proposed Solution

A supported compaction receipt must wait for safe membership-retirement semantics. Diagnostic counting that retains evidence can be a narrower independent card, but is not the current compact-and-remove proposal.

Historical approach to reconcile:
Current architecture rules take precedence: parsing/encoding stays at adapters, domain concepts are runtime-backed, no trust casts are introduced, and tests run in Docker.
ORSet.compact(includedVV) currently mutates the set in place and
returns nothing. The caller has to diff before/after metrics manually
(GCPolicy does this with collectGCMetrics).

Instead: compact() returns a CompactionReceipt — a frozen value
object with { dotsRemoved: number, elementsRemoved: number }. The
caller gets structured feedback without manual diffing.

const receipt = state.nodeAlive.compact(appliedVV);
logger.info(`GC: removed ${receipt.dotsRemoved} dots`);

This aligns with the Systems-Style manifesto: structured data stays
structured (no "count before, count after, subtract" pattern).

2c. Alternatives considered and rejected

No additional alternatives are recorded as decided. Reject duplicate ownership, private-import escape hatches and a broken intermediate mainline; retain original alternatives below when present.

2d. Acceptance Criteria

• Safe membership compaction returns an immutable truthful receipt after GC membership compaction can resurrect removed nodes when stale additions rejoin #911’s retirement contract; genuinely concurrent additions survive and receipt counts match actual retained/removed evidence.
• The issue-specific positive and negative witnesses in Test Plan pass; relevant compatibility and failure behavior are recorded.

2e. Test Plan

Golden: Compare the declared CRDT result with an independent expected-state witness.

Edges: Empty operations, concurrent additions/removes, replay permutations and checkpoint round trips.

Known failure modes: Malformed inputs or stale evidence cannot silently change membership/causality.

Fuzz and stress: Deterministic writer schedules and join permutations; include a calibrated broken control.

All tests and benchmarks execute in COPY-based Docker containers without host repository or Git-directory mounts. This planning audit does not claim those checks were run.

3. Prerequisites

Completion prerequisites; preparatory work may start earlier.

• #911: Use this receipt feature only for a safe compaction contract: it must not turn the known unsafe membership retirement into a supported GC operation. Safety/admissible-merge semantics precede the advertised dotsRemoved receipt.

4. Scope

In: A supported compaction receipt must wait for safe membership-retirement semantics. Diagnostic counting that retains evidence can be a narrower independent card, but is not the current compact-and-remove proposal.

Out: unrelated domain work and any expansion beyond the issue’s stated observable outcome.

Safe intermediate state: the PR builds and passes relevant checks after its listed prerequisites; existing supported behavior remains usable. Any preparatory step must be independently mergeable.

5. Why now

Maintainer ordering: memory correctness first, supported attachments next, then land eligible PRs. Preserve this card’s existing priority unless a separately recorded scope decision changes it.

6. Risks

Main risk: implementing the historical description instead of the current runtime contract. Preserve compatibility, causal/ownership invariants and bounded behavior relevant to crdt.

7. Definition of Done

The issue-specific acceptance checks pass, relevant validation evidence is attached, and the issue links the coherent PR and resulting mainline integration commit. No open item is hidden in a later repair PR.

8. Stakeholders

James Ross: maintainer, assignee and acceptance owner. git-warp contributors and consumers rely on this domain’s supported contract and reproducible evidence.

9. Related Issues

No additional downstream blocker is established. Shared domain membership alone is not a prerequisite.

Historical paths, counts, release names and shell examples in source material are evidence to reconcile, not authority to restore retired documentation or run host tests.