Prototype the deep Analysis ingestion module interface

[fproulx-boostsecurity]

Question

What smallest deep module interface should Kitchen call to reconcile one completed Analysis result into canonical Pantry while hiding candidate construction, preservation rules, metrics, persistence adaptation, and committed-state publication?

Compare at least two meaningfully different interface shapes and build a cheap Go skeleton or test harness for maintainer reaction. Resolve input, result, error, ordering, and performance invariants. Do not implement production behavior.

[fproulx-boostsecurity]

Prototype ready for the interface decision.

Asset:

• Branch: https://github.com/boostsecurityio/smokedmeat/tree/prototype/analysis-ingestion-interface
• Commit: a4916f2
• Run locally: make prototype-analysis-ingestion

The prototype applies the same commit, partial-phase, confirmed-gone, no-op, and persistence-failure scenarios to three seams:

1. Minimal completed-result commit: Ingest(ctx, poutine.AnalysisResult) error. Deepest and smallest Pantry-facing seam. The caller only knows committed versus failed. Reconciliation notice wording remains publication or Counter contract work.
2. Prepared lifecycle: Prepare then Commit with an opaque capability and summary. Supports preview and audit, but exposes ordering, lifecycle, revision, and removal details no current caller needs.
3. Caller-shaped flow: Run(ctx, AnalyzeRequest). Makes the current handler smallest, but couples Pantry ingestion to remote Analysis execution and progress concerns.

Recommendation: choose 1. Keep Analysis execution outside the ingestion module, accept only a completed canonical result, and hide candidate construction, persistence, live replacement, publication, locking, metrics, and BBolt behind the module. This gives issue #102 a narrow transaction boundary without committing the design to one remote caller.

This ticket remains open pending maintainer reaction to the prototype.

[fproulx-boostsecurity]

Resolution

Choose the minimal completed-result ingestion seam:

type AnalysisIngestor struct {
    // Pantry transaction and publication dependencies are private.
}

func (i *AnalysisIngestor) Ingest(
    ctx context.Context,
    completed poutine.AnalysisResult,
) error

The prototype and maintainer reaction establish these constraints:

• Analysis execution and progress remain outside the ingestion module. The input is one completed, normalized poutine.AnalysisResult carrying the per-phase authority and existence evidence selected in Define successful repository scope evidence for Analysis ingestion #103.
• Ingest is the only caller-visible reconciliation operation. It does not expose prepare/commit ordering, candidate objects, revisions, mutation counts, locks, BBolt, metrics, or publication mechanics.
• A nil result means the completed evidence was accepted and is either durably committed and published or is a trustworthy no-op. An error means the prior committed Pantry remains authoritative.
• The module applies the ownership and preservation rules selected in Define the Analysis reconciliation ownership matrix #104, then delegates the atomic candidate-to-committed-state transition to the Pantry seam selected in Prototype the Pantry committed-state transaction interface #102.
• Confirmed-gone operator notice content is not part of this interface. It travels with committed publication and is finalized by the Counter-Kitchen contract work.
• Use a concrete module type. Add narrow internal adapters only at real substitution boundaries such as persistence; do not add a public Go interface for a single implementation.

Prototype asset: https://github.com/boostsecurityio/smokedmeat/tree/prototype/analysis-ingestion-interface

Maintainer approved option 1 on 2026-07-29.