B4.3a: Resolve permanently failed billing periods without reopening history

[ScottArbeit]

September 7 recovery status

Inactive historical proposal. Its permanently failed-period and settlement model is not selected. Issue #576 keeps calculation failures retryable, and this issue must not block a usage-only read. Any terminal failure or manual settlement lifecycle needs a later explicit product decision.

Scott approved D1-D5 in Issue #554. That parent now controls selected scope and current dev-process execution. The original proposal below is retained as historical evidence, not an assignment to resume it.

Historical proposal

B4.3a: Resolve permanently failed billing periods without reopening history

Parent mini-epic: #560 - WS4: Pricing, billing, and owner usage
Depends on: #576

Objective

Provide the separately created replacement or manual-settlement workflow required when #576 permanently fails an owner-scoped billing period because deterministic charge calculation exceeded the supported numeric range.

Why This Matters

A permanently failed period must remain honest and immutable, but Grace Operators still need a deliberate way to produce a settled owner-accounting outcome without reopening or rewriting the failed history.

Product-Decision Gate

Before coding, run a focused product-direction session that selects the supported outcome: replacement period, manual
settlement, or both. The decision must define identity, linkage to the failed period, pricing/evidence requirements,
operator provenance, visibility, and retry/idempotency. Do not infer these contracts from #576.

Invariants

• The original permanently failed BillingPeriod never reopens, becomes Closed/Corrected, or has its failure evidence erased.
• Every replacement or settlement record has a new identity and an immutable link to the failed original period.
• Scope remains exactly OwnerId with optional OrganizationId and RepositoryId plus the same half-open UTC month.
• No second billing identity is introduced.
• No posted ledger row or supporting historical pricing/source evidence is mutated or deleted.
• Operator principal, reason, and correlation are required and width-validated before mutation.
• Exact retries converge idempotently; conflicting correlation reuse fails clearly.
• This issue never receives, settles, or creates a workflow for a fact accepted after its exact BillingPeriod is
  PermanentlyFailed.

Forbidden Or Sensitive Shapes

• Do not modify src/Grace.slnx.
• Do not reuse the failed period ID, clear its failure state, or disguise settlement as an ordinary close retry.
• Do not automatically synthesize historical pricing or settlement values.
• Do not add external invoice-provider behavior.
• Do not add an HTTP/CLI surface until the selected contract is propagated through B4.4: Implement Grace.Operations.Api owner usage endpoints #577/B4.5: Implement Grace Server proxy for owner usage #578 or a separately named leaf.
• Do not create a settlement handoff, rejection path, pending state, sibling issue, test, or proof for invalid
  3574960808.

Required Proof

• Positive: selected operator workflow creates a new linked outcome and leaves the failed original byte-for-byte immutable in protected fields.
• Negative: nonfailed source period, wrong scope/month, missing provenance, conflicting replay, unsupported currency/pricing evidence, and direct SQL bypass fail without partial mutation.
• Boundary: half-open UTC month, maximum correlation width, zero values where allowed, and numeric range boundaries.
• Concurrency/recovery: repeated commands and competing operators create at most one outcome per selected identity; transaction failure and restart converge without orphaned ledger/evidence.
• Regression: B4.3 replacement mini-epic: owner billing close and corrections #576 permanent-failure state cannot enter ordinary close/retry; B4.4: Implement Grace.Operations.Api owner usage endpoints #577/B4.5: Implement Grace Server proxy for owner usage #578 contract propagation is updated or explicitly deferred to a named child before merge.

Contract Propagation Map

• Operations entities, EF configuration, migration/snapshot/frozen model, SQL constraints/triggers: required after product decision.
• Internal settlement service and operator provenance: required.
• HTTP, CLI, SDK, OpenAPI/generated clients: deferred to B4.4: Implement Grace.Operations.Api owner usage endpoints #577/B4.5: Implement Grace Server proxy for owner usage #578 unless the product decision creates a separate named leaf.
• Documentation and focused/full validation: required.

Validation And Definition Of Done

• Product decision is recorded before a coding worker is assigned.
• The issue-owned branch starts from current origin/epic/560-operations-pricing-billing-usage after B4.3 replacement mini-epic: owner billing close and corrections #576 merges and targets that mini-epic branch.
• Scoped Fantomas and one final pwsh ./scripts/validate.ps1 -Full pass.
• GitHub Full and latest-head Codex Code Review Bot pass.
• src/Grace.slnx remains untouched.

PR #712 Session 8 Scope Boundary

• 3574960808 is invalid and is not B4.3a: Resolve permanently failed billing periods without reopening history #715 work. Grace never accepts a valid fact after its exact BillingPeriod is
  PermanentlyFailed; this issue does not turn that rejected premise into a settlement, replacement, pending state,
  workflow, or proof.
• B4.3a: Resolve permanently failed billing periods without reopening history #715 remains limited to separately approved manual outcomes, including deferred 3574039853, without reopening or
  mutating the original period or its immutable evidence.

PR #712 Session 6 Deferred Finding

• 3574039853: a zero-entry Closed period may later receive a fact whose mapping exists but whose historical PricingRate is absent. The approved B4.3 replacement mini-epic: owner billing close and corrections #576 contract forbids automatic historical-pricing repair and keeps the automatic correction pending until a separately approved manual outcome. Do not weaken pricing-history guards or insert historical rates in B4.3 replacement mini-epic: owner billing close and corrections #576.
• B4.3a: Resolve permanently failed billing periods without reopening history #715 must define how replacement/manual settlement resolves this pending late-correction case without mutating the original Closed/Corrected period, posted ledger history, or protected historical pricing. Proof must cover operator visibility, provenance, idempotent retry, bounded failure evidence, and the absence of automatic historical pricing insertion.