… follow-on)

Closes the remaining safety gap from #111: when a prior run left a package
in PackageState::Ambiguous (reconciliation was inconclusive at that time),
a subsequent `shipper resume` previously fell through to blind cargo retry.
That risked re-uploading a crate whose original upload may have actually
succeeded.

## What this adds

Both the sequential (engine::mod) and parallel (engine::parallel::publish)
publish paths now detect `PackageState::Ambiguous` BEFORE any cargo
activity and reconcile against registry truth first.

Outcomes follow the same state machine as in-flight reconciliation:

- **Published** → mark Published, skip any further cargo work for this
  crate, continue/return success receipt with no republish.
- **NotPublished** → clear Ambiguous back to Pending (registry confirms
  no prior upload), fall through to the normal publish flow.
- **StillUnknown** → emit PublishFailed webhook + halt with an
  operator-actionable error; do NOT retry.

## Parallel + sequential symmetry

- Sequential: new `sequential_reconcile` helper in engine::mod wraps the
  full `RegistryClient::is_version_visible_with_backoff` and returns the
  same `(ReconciliationOutcome, Vec<ReadinessEvidence>)` shape as the
  parallel path's helper. Called from the per-package state-check match
  arm.
- Parallel: reuses existing `reconcile_ambiguous_upload` from
  engine::parallel::reconcile. Called just before the retry-loop entry,
  returning a completed PackageResult early on Published or StillUnknown.

Both paths emit `PublishReconciling` and `PublishReconciled` events so
the event stream records the resume-time reconciliation alongside any
in-flight reconciliation from earlier runs.

## Test plan

- [x] `cargo clippy --all-targets -- -D warnings` clean
- [x] `cargo fmt --check` clean
- [x] 192 engine tests pass (no regressions)

BDD scenarios for resume-path reconciliation across all three outcomes
are a natural follow-up; the handler shape mirrors the in-flight path so
regressions here surface through existing integration tests that already
cover the outcome shape.

## Related

- Parent: #99 Reconcile (the biggest non-cosmetic safety gap from the
  v0.3.0-rc.1 retrospective)
- Sibling PRs already merged: #111 (in-flight reconcile), #112 (events-
  as-truth), #113 (retry narration), #114 (registry-aware backoff)
- Master roadmap: #109

… follow-on) (#115)

Closes the remaining safety gap from #111: when a prior run left a package
in PackageState::Ambiguous (reconciliation was inconclusive at that time),
a subsequent `shipper resume` previously fell through to blind cargo retry.
That risked re-uploading a crate whose original upload may have actually
succeeded.

## What this adds

Both the sequential (engine::mod) and parallel (engine::parallel::publish)
publish paths now detect `PackageState::Ambiguous` BEFORE any cargo
activity and reconcile against registry truth first.

Outcomes follow the same state machine as in-flight reconciliation:

- **Published** → mark Published, skip any further cargo work for this
  crate, continue/return success receipt with no republish.
- **NotPublished** → clear Ambiguous back to Pending (registry confirms
  no prior upload), fall through to the normal publish flow.
- **StillUnknown** → emit PublishFailed webhook + halt with an
  operator-actionable error; do NOT retry.

## Parallel + sequential symmetry

- Sequential: new `sequential_reconcile` helper in engine::mod wraps the
  full `RegistryClient::is_version_visible_with_backoff` and returns the
  same `(ReconciliationOutcome, Vec<ReadinessEvidence>)` shape as the
  parallel path's helper. Called from the per-package state-check match
  arm.
- Parallel: reuses existing `reconcile_ambiguous_upload` from
  engine::parallel::reconcile. Called just before the retry-loop entry,
  returning a completed PackageResult early on Published or StillUnknown.

Both paths emit `PublishReconciling` and `PublishReconciled` events so
the event stream records the resume-time reconciliation alongside any
in-flight reconciliation from earlier runs.

## Test plan

- [x] `cargo clippy --all-targets -- -D warnings` clean
- [x] `cargo fmt --check` clean
- [x] 192 engine tests pass (no regressions)

BDD scenarios for resume-path reconciliation across all three outcomes
are a natural follow-up; the handler shape mirrors the in-flight path so
regressions here surface through existing integration tests that already
cover the outcome shape.

## Related

- Parent: #99 Reconcile (the biggest non-cosmetic safety gap from the
  v0.3.0-rc.1 retrospective)
- Sibling PRs already merged: #111 (in-flight reconcile), #112 (events-
  as-truth), #113 (retry narration), #114 (registry-aware backoff)
- Master roadmap: #109

…low-on)

Closes one of the remaining #99 follow-ons identified in the
retrospectives: make it explicit, in the rustdoc that downstream tooling
and contributors will actually read, that cargo's stdout/stderr output is
a classification HINT for Shipper's retry loop — not the authoritative
answer about what happened.

## What this changes

- `ErrorClass` rustdoc (shipper-types): adds a "Classification is a hint,
  not truth" section explaining that pattern-matching cargo text drives
  retry scheduling but ambiguous outcomes MUST be reconciled against
  registry truth. Cross-refs ReconciliationOutcome and the reconcile
  module.
- `classify_cargo_failure` rustdoc (shipper::runtime::execution): states
  up-front "This is a hint, not authoritative truth" and points at the
  reconcile flow for the authoritative resolution on Ambiguous outcomes.
- `docs/explanation/why-shipper.md` gains a new section "Cargo stdout is
  a hint; the registry is the truth" making the same point at the product
  level — and connecting it to why Shipper can be safer than a naive
  shell-script `cargo publish` loop.

## Why this matters

Contributors reading `ErrorClass` and wondering "can I just pattern-match
more cargo strings?" now see the contract: cargo text is the fast-path
hint, registry queries are truth. The reconcile flow introduced in #111
(in-flight) and #115 (resume-path) is now documented as the authoritative
side of that contract, not just implemented.

## Scope

Pure docs/rustdoc change. No code changes. No schema changes. No
snapshot churn. Covered by existing tests.

- `cargo doc --no-deps -Dwarnings` clean
- `cargo test -p shipper-types` + `-p shipper --lib runtime::execution`
  pass (no regressions)

## Related

- Parent: #99 Reconcile
- Prior PRs: #111 (in-flight reconcile), #115 (resume-path reconcile)
- Pillar: Reconcile (#102)

…low-on) (#117)

Closes one of the remaining #99 follow-ons identified in the
retrospectives: make it explicit, in the rustdoc that downstream tooling
and contributors will actually read, that cargo's stdout/stderr output is
a classification HINT for Shipper's retry loop — not the authoritative
answer about what happened.

## What this changes

- `ErrorClass` rustdoc (shipper-types): adds a "Classification is a hint,
  not truth" section explaining that pattern-matching cargo text drives
  retry scheduling but ambiguous outcomes MUST be reconciled against
  registry truth. Cross-refs ReconciliationOutcome and the reconcile
  module.
- `classify_cargo_failure` rustdoc (shipper::runtime::execution): states
  up-front "This is a hint, not authoritative truth" and points at the
  reconcile flow for the authoritative resolution on Ambiguous outcomes.
- `docs/explanation/why-shipper.md` gains a new section "Cargo stdout is
  a hint; the registry is the truth" making the same point at the product
  level — and connecting it to why Shipper can be safer than a naive
  shell-script `cargo publish` loop.

## Why this matters

Contributors reading `ErrorClass` and wondering "can I just pattern-match
more cargo strings?" now see the contract: cargo text is the fast-path
hint, registry queries are truth. The reconcile flow introduced in #111
(in-flight) and #115 (resume-path) is now documented as the authoritative
side of that contract, not just implemented.

## Scope

Pure docs/rustdoc change. No code changes. No schema changes. No
snapshot churn. Covered by existing tests.

- `cargo doc --no-deps -Dwarnings` clean
- `cargo test -p shipper-types` + `-p shipper --lib runtime::execution`
  pass (no regressions)

## Related

- Parent: #99 Reconcile
- Prior PRs: #111 (in-flight reconcile), #115 (resume-path reconcile)
- Pillar: Reconcile (#102)

…omes (#99 follow-on)

Closes the last remaining #99 follow-on: end-to-end integration coverage
for the three reconciliation outcomes the state machine can produce.

## Three scenarios added to engine::parallel::tests

Each exercises publish_package() against a real tiny_http mock registry
with a fake cargo binary configured to exit ambiguously (exit 1, empty
stdout/stderr — which classify_publish_failure maps to
CargoFailureClass::Ambiguous per existing unit tests).

Readiness polling is disabled (readiness.enabled = false) so each
reconcile site reduces to a single registry query — avoids flaky request
counts that a full polling loop would produce.

### 1. reconcile_bdd_ambiguous_resolves_to_published

- cargo fails ambiguously
- entry + post-cargo quick checks return 404
- reconcile's single version_exists poll returns 200
- expected: PackageState::Published, attempts=1 (no second cargo)
- verifies PublishReconciling + PublishReconciled{Published} events
  emitted to the on-disk event log

### 2. reconcile_bdd_ambiguous_resolves_to_not_published_then_retries

- cargo fails ambiguously on every attempt
- registry consistently returns 404
- reconcile resolves to NotPublished, falls through to normal retry
- after max_attempts=2, package ends Failed
- verifies PublishReconciled{NotPublished} event emitted
- verifies cargo was actually retried (attempts=2)

### 3. reconcile_bdd_resume_from_ambiguous_state_skips_republish

- state pre-seeded with PackageState::Ambiguous (simulating a prior
  interrupted run)
- entry check returns 404 (bypasses "already published" short-circuit)
- resume-path reconcile (from PR #115) fires BEFORE retry loop
- single version_exists query returns 200 → Published
- expected: attempts=0 (cargo NOT invoked)
- verifies via SHIPPER_CARGO_ARGS_LOG that cargo binary was never called
- verifies PublishReconciling + PublishReconciled{Published} events emitted

## Verification

- cargo test -p shipper --lib -- reconcile_bdd: 3 pass
- cargo test -p shipper --lib -- engine::parallel: 70 pass (no regressions)
- cargo clippy --all-targets -- -D warnings: clean
- cargo fmt --check: clean

## Why events are read from disk

publish_package flushes event batches to events.jsonl and clears the
in-memory log after each write. Assertions read via
EventLog::read_from_file(&events_path) to see the full persisted stream.

## #99 tracker after this merge

- [x] In-flight reconcile state machine (#111)
- [x] Resume-path reconciliation (#115)
- [x] Docs/contracts: cargo text is a hint, registry is truth (#117)
- [x] BDD integration scenarios for all 3 outcomes (this PR)

#99 is now fully closed.

…omes (#99 follow-on) (#119)

Closes the last remaining #99 follow-on: end-to-end integration coverage
for the three reconciliation outcomes the state machine can produce.

## Three scenarios added to engine::parallel::tests

Each exercises publish_package() against a real tiny_http mock registry
with a fake cargo binary configured to exit ambiguously (exit 1, empty
stdout/stderr — which classify_publish_failure maps to
CargoFailureClass::Ambiguous per existing unit tests).

Readiness polling is disabled (readiness.enabled = false) so each
reconcile site reduces to a single registry query — avoids flaky request
counts that a full polling loop would produce.

### 1. reconcile_bdd_ambiguous_resolves_to_published

- cargo fails ambiguously
- entry + post-cargo quick checks return 404
- reconcile's single version_exists poll returns 200
- expected: PackageState::Published, attempts=1 (no second cargo)
- verifies PublishReconciling + PublishReconciled{Published} events
  emitted to the on-disk event log

### 2. reconcile_bdd_ambiguous_resolves_to_not_published_then_retries

- cargo fails ambiguously on every attempt
- registry consistently returns 404
- reconcile resolves to NotPublished, falls through to normal retry
- after max_attempts=2, package ends Failed
- verifies PublishReconciled{NotPublished} event emitted
- verifies cargo was actually retried (attempts=2)

### 3. reconcile_bdd_resume_from_ambiguous_state_skips_republish

- state pre-seeded with PackageState::Ambiguous (simulating a prior
  interrupted run)
- entry check returns 404 (bypasses "already published" short-circuit)
- resume-path reconcile (from PR #115) fires BEFORE retry loop
- single version_exists query returns 200 → Published
- expected: attempts=0 (cargo NOT invoked)
- verifies via SHIPPER_CARGO_ARGS_LOG that cargo binary was never called
- verifies PublishReconciling + PublishReconciled{Published} events emitted

## Verification

- cargo test -p shipper --lib -- reconcile_bdd: 3 pass
- cargo test -p shipper --lib -- engine::parallel: 70 pass (no regressions)
- cargo clippy --all-targets -- -D warnings: clean
- cargo fmt --check: clean

## Why events are read from disk

publish_package flushes event batches to events.jsonl and clears the
in-memory log after each write. Assertions read via
EventLog::read_from_file(&events_path) to see the full persisted stream.

## #99 tracker after this merge

- [x] In-flight reconcile state machine (#111)
- [x] Resume-path reconciliation (#115)
- [x] Docs/contracts: cargo text is a hint, registry is truth (#117)
- [x] BDD integration scenarios for all 3 outcomes (this PR)

#99 is now fully closed.

… follow-on)

Completes the third acceptance-criteria BDD scenario for #99. The existing
suite already covered Published (registry confirms upload landed) and
NotPublished (registry confirms upload didn't land); this adds the
operator-actionable StillUnknown case where reconciliation itself can't
reach a verdict because the registry is unhealthy.

Setup drives every registry query on /api/v1/crates/demo/0.1.0 to 500,
so version_exists bails with Err for non-200/404 statuses.
reconcile_ambiguous_upload translates that Err into
ReconciliationOutcome::StillUnknown.

Asserts:
  - publish returns Err with "reconciliation inconclusive" message
  - package state is PackageState::Ambiguous (so resume's reconcile
    block will fire rather than a silent retry)
  - exactly one cargo invocation — StillUnknown must not blind-retry
  - PublishReconciling + PublishReconciled{ StillUnknown } events
    are persisted to events.jsonl for operator visibility

Closes the last open AC on #99 acceptance list; reconciliation behavior
itself was already implemented in PR #111 and PR #115.

… follow-on) (#144)

Completes the third acceptance-criteria BDD scenario for #99. The existing
suite already covered Published (registry confirms upload landed) and
NotPublished (registry confirms upload didn't land); this adds the
operator-actionable StillUnknown case where reconciliation itself can't
reach a verdict because the registry is unhealthy.

Setup drives every registry query on /api/v1/crates/demo/0.1.0 to 500,
so version_exists bails with Err for non-200/404 statuses.
reconcile_ambiguous_upload translates that Err into
ReconciliationOutcome::StillUnknown.

Asserts:
  - publish returns Err with "reconciliation inconclusive" message
  - package state is PackageState::Ambiguous (so resume's reconcile
    block will fire rather than a silent retry)
  - exactly one cargo invocation — StillUnknown must not blind-retry
  - PublishReconciling + PublishReconciled{ StillUnknown } events
    are persisted to events.jsonl for operator visibility

Closes the last open AC on #99 acceptance list; reconciliation behavior
itself was already implemented in PR #111 and PR #115.