Choose the Counter-Kitchen reconciliation outcome contract

[fproulx-boostsecurity]

Question

What exact Kitchen HTTP, Counter client, and Counter TUI contract should report Analysis completion separately from Pantry reconciliation commit success or failure?

Resolve synchronous response and recovery-poll shapes, sanitized failure representation, when Counter fetches committed Pantry, how it retains the last committed Pantry on failure, removal of local pruning and re-import, interaction with existing progress and metadata-sync messages, and the explicit rerun retry path while preserving current operator behavior.

[fproulx-boostsecurity]

Resolution

One identified Analysis run now has one canonical Counter-Kitchen outcome contract. Every request requires a client-generated analysis_id, a session_id, and a typed scope for one Organization, one Repository, or an explicit Repository set. Workflow Analysis always runs; the engine-neutral secret_detection option requests that independent phase. Kitchen, not Counter, orchestrates Repository sets and produces one canonical result.

Response model

The synchronous response and GET /analyze/result/{id} return the same envelope:

{
  "analysis_id": "analysis_123",
  "analysis": {
    "status": "completed",
    "result": {}
  },
  "loot": {
    "status": "committed"
  },
  "reconciliation": {
    "status": "committed",
    "pantry_revision": 42
  }
}

The independent statuses are:

• Analysis: pending, completed, or failed
• Loot, when credential material exists: pending, committed, or failed
• Reconciliation after completed Analysis: pending, committed, or failed

A trustworthy partial result is completed; per-Repository phase outcomes describe failures and skips. A completed Analysis returns HTTP success even if Loot persistence or Pantry reconciliation failed. Request validation or failure to produce a trustworthy Analysis result remains a non-success response. A committed or no-op reconciliation reports the current Pantry revision and no server mutation counts.

All external failures use stable codes and fixed safe messages. Arbitrary truncated internal errors do not appear in responses, per-Repository diagnostics, History, or the TUI. Kitchen logs retain safely scrubbed operational detail correlated by Analysis ID.

Lifecycle and recovery

After validation and registration, a Kitchen-owned bounded context continues the Analysis run if the POST connection drops. Reusing an ID never starts a duplicate: Kitchen returns 409 Conflict with analysis_id_conflict and a recovery Location. Wrong-Session lookups reveal no run state.

Known recovery records return HTTP success. Unknown, expired, or wrong-Session IDs return 404; there is no unknown status. Session-scoped envelopes remain in memory for two hours after their latest state change and do not survive Kitchen restart. Counter polls an ambiguous dropped response until the configured Analysis timeout plus one minute, starting at two-second intervals and backing off to ten seconds. Three consecutive 404 responses end recovery. A restart or expiry causes Counter to fetch current Pantry without claiming that the unavailable run produced it.

Counter supports one active Analysis run. Kitchen may run Analyses from different clients or Sessions concurrently. There is no automatic request resubmission, Analysis replay, or reconciliation replay. Rerunning analyze or deep-analyze creates a new ID and fresh evidence.

Loot and Pantry

Kitchen persists all credential Loot from one result atomically and independently before Pantry reconciliation. Reconciliation continues after Loot failure. Committed credentials enter Counter's visible Loot stash immediately. Credentials whose persistence failed remain visibly marked as not persisted for the current Counter process so usable material is not discarded.

Counter never prunes, imports, or aggregates Pantry state from the Analysis result. After committed reconciliation it keeps a local snapshot already at or beyond the reported revision or fetches a qualifying snapshot. Counter makes one immediate fetch and three retries after one, two, and four seconds, each with a ten-second timeout. It retains the previous complete Pantry until success and accepts a valid empty snapshot. Exhaustion leaves the prior Pantry visible and tells the Operator which revision committed, which revision is displayed, and that reconnecting refreshes Pantry.

Reconciliation failure is shown separately from Analysis completion. Setup offers r to rerun the complete Analysis or Enter to continue with the last committed Pantry. The result remains available for summaries, warnings, history presentation, and credential display, never as locally constructed graph state.

Progress, metadata, History, and tree behavior

WebSocket progress remains advisory. Its phases are workflow_analysis, secret_scan, and reconciliation; only the HTTP response or recovery poll establishes terminal outcomes.

Repository metadata sync remains an independent asynchronous follow-up. It may update Known Entities and repository access properties after Analysis reconciliation failure, but never imports the failed Analysis evidence. Completion reports its Pantry revision for a qualifying Counter refresh.

Kitchen, not Counter, persists one terminal History record per Analysis ID. The record contains the Analysis summary, Loot status when applicable, reconciliation status, Pantry revision, or stable failure codes. Counter does not create a duplicate after receiving the response.

After a qualifying snapshot applies confirmed-gone evidence, Counter announces the explicit removed scopes and states that Loot and History were preserved. Multiple removals use a bounded sample and count. Focus moves to the nearest surviving ancestor or the Pantry root without a modal or confirmation.

Interface and compatibility

The Counter client collapses the current standard, deep, ID, and rule-pack variants into one structured Analyze operation and one Analysis-run lookup. Both return the same domain envelope. The transport-level deep flag becomes the engine-neutral secret_detection option.

This is a clean schema 3.0 contract. There is no compatibility normalization for old result or response shapes, no Counter graph importer, and no client-side multi-Repository aggregation.

The durable decision is recorded in CONTEXT.md, ADR-0002, and ADR-0003 at commit df1a233.