feat(cost): amortized fixed-cost attribution for shared pool runs (calque#102)

cost.Measured gains WarmHit (default false = today's dedicated-acquisition
behavior, unchanged for every existing caller). Verdict now labels which
fixed-cost regime produced a K — DEDICATED ACQUISITION (this run paid the
full acquire+enter alone) vs WARM HIT (this run reused an already-loaded
pool worker) — mirroring the existing occupancy-scope labeling discipline
so a reader can't mistake one regime's fixed cost for the other's.

internal/pool's Worker now captures whether the runner was already warm
BEFORE each claim's drain (not after — DrainBatch always leaves it warm on
a clean finish, which would make every claim after the pool's first look
like a hit) and reports it in the completion summary via ResultWriter's
new warmHit param, so a future submitter (#103) can set
cost.Measured.WarmHit honestly per claim.

Author: scttfrdmn

internal/cost/cost.go

@@ -26,6 +26,22 @@ type Measured struct {
 	// for before any work) + any warm-idle; part of the AWS rectangle (§8).
 	AcquireSeconds float64
 	EnterSeconds   float64 // one-time warm @enter load (amortized across items)
+
+	// WarmHit is true when THIS run's AcquireSeconds/EnterSeconds reflect a
+	// shared-pool warm hit (calque#100/#101's pool worker was already resident
+	// and loaded — the caller reports near-zero fixed cost for this run) rather
+	// than a dedicated acquire-and-load (the pool/session/real default: this run
+	// paid the FULL fixed cost alone, per docs/pool-queue-contract.md). It does
+	// not change how the model computes anything — AcquireSeconds/EnterSeconds
+	// are used exactly as given either way — it only changes what the verdict
+	// SAYS about what those numbers mean, so a reader doesn't assume a hit's
+	// near-zero fixed cost is the STEADY STATE for every run against a shared
+	// pool (most runs might hit; the one that triggers a cold load pays the
+	// whole fixed cost alone, and reporting every run's K as if it were that one
+	// misattributes cost, exactly as reporting every run's K as if it always hit
+	// warm would understate it). Zero-value (false) is today's existing
+	// dedicated-acquisition behavior — no change for any pre-#102 caller.
+	WarmHit bool
 }
 
 // SideCost is one side's total dollars at a given item count.
@@ -256,9 +272,24 @@ func (m *Model) Verdict(atItems int) (string, error) {
 		fmt.Fprintf(&b, "NOTE: occupancy is a WHOLE-RUN mean (includes %s), so it\n"+
 			"      understates steady-state GPU fill and makes this K pessimistic for AWS.\n", load)
 	}
+	fmt.Fprintf(&b, "%s\n", m.warmHitLabel())
 	return b.String(), nil
 }
 
+// warmHitLabel names WHICH fixed-cost regime this K's AcquireSeconds/EnterSeconds
+// came from (calque#102), mirroring occScopeLabel's discipline: an amortized-cost
+// number is only auditable if the reader is told which regime produced it, not
+// left to assume every run against a shared pool costs the same as this one.
+func (m *Model) warmHitLabel() string {
+	if m.M.WarmHit {
+		return "Fixed cost regime: WARM HIT — this run reused an already-loaded pool worker " +
+			"(near-zero acquire+enter); most runs against a healthy pool look like this, but the " +
+			"run that triggers a cold load pays the full fixed cost alone (see a non-warm-hit K for that number)."
+	}
+	return "Fixed cost regime: DEDICATED ACQUISITION — this run paid the full acquire+enter cost alone " +
+		"(today's default outside a shared pool; calque#100/#101)."
+}
+
 // occScopeLabel renders the occupancy window for the verdict line.
 func (m *Model) occScopeLabel() string {
 	switch m.M.OccupancyScope {

internal/cost/cost_test.go

@@ -179,3 +179,44 @@ func TestVerdictLabelsOccupancyScope(t *testing.T) {
 		t.Errorf("unlabeled occupancy must warn like whole_run does, got:\n%s", v3)
 	}
 }
+
+// TestVerdictLabelsFixedCostRegime proves K declares WHETHER its
+// AcquireSeconds/EnterSeconds came from a shared-pool warm hit or a dedicated
+// acquisition (calque#102) — the same near-zero fixed cost means two very
+// different things (steady state for most pool runs vs. this SPECIFIC run's
+// full cost) depending on which regime produced it, mirroring
+// TestVerdictLabelsOccupancyScope's occupancy-scope discipline.
+func TestVerdictLabelsFixedCostRegime(t *testing.T) {
+	r := loadTestRates(t)
+	base := Measured{
+		CardAskedFor: "H100", InstanceUsed: "g7e.2xlarge",
+		SecPerItem: 0.5, Occupancy: 0.95, SampleItems: 100,
+	}
+
+	dedicated := base
+	dedicated.AcquireSeconds, dedicated.EnterSeconds = 120, 30
+	v, err := (&Model{Rates: r, M: dedicated}).Verdict(100000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(v, "DEDICATED ACQUISITION") {
+		t.Errorf("default (WarmHit=false) K must label itself DEDICATED ACQUISITION, got:\n%s", v)
+	}
+	if strings.Contains(v, "WARM HIT") {
+		t.Errorf("dedicated-acquisition K must NOT claim a warm hit, got:\n%s", v)
+	}
+
+	warmHit := base
+	warmHit.AcquireSeconds, warmHit.EnterSeconds = 0, 0 // this run reused an already-loaded worker
+	warmHit.WarmHit = true
+	v2, err := (&Model{Rates: r, M: warmHit}).Verdict(100000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(v2, "WARM HIT") {
+		t.Errorf("WarmHit=true K must label itself WARM HIT, got:\n%s", v2)
+	}
+	if strings.Contains(v2, "DEDICATED ACQUISITION") {
+		t.Errorf("warm-hit K must NOT claim a dedicated acquisition, got:\n%s", v2)
+	}
+}

internal/pool/pool.go

@@ -72,10 +72,13 @@ type ResultWriter interface {
 	// batch — implementations key it by the manifest's own Bucket/ResultPrefix
 	// so concurrent claims' results never collide.
 	Sink(man calexec.Manifest) warm.Sink
-	// WriteSummary persists the claim's completion record (failed indices) so
-	// a submitter polling man.SummaryKey (via calexec.WaitForSummary, reused
-	// unmodified) observes the claim as done.
-	WriteSummary(ctx context.Context, man calexec.Manifest, failed []int) error
+	// WriteSummary persists the claim's completion record (failed indices,
+	// plus warmHit — calque#102: was the resident runner already warm and
+	// loaded when this claim was served, or did this claim pay a fresh
+	// acquire+@enter?) so a submitter polling man.SummaryKey (via
+	// calexec.WaitForSummary, reused unmodified) observes the claim as done
+	// AND knows which fixed-cost regime to feed cost.Measured.WarmHit with.
+	WriteSummary(ctx context.Context, man calexec.Manifest, failed []int, warmHit bool) error
 }
 
 // Queue is the slice of spawn's taskpool.Queue this package needs — an
@@ -201,7 +204,13 @@ func (w *Worker) runOne(ctx context.Context, ref ClaimRef, receipt string) {
 		return
 	}
 
-	if !w.Supervisor.IsWarm() {
+	// Capture BEFORE DrainBatch: this is "was the runner already warm when THIS
+	// claim arrived" (calque#102's WarmHit), not "is it warm now" (DrainBatch
+	// always leaves it warm on a clean drain, which would make every claim
+	// after the pool's first look like a hit regardless of whether IT paid a
+	// reload after a crash).
+	wasWarm := w.Supervisor.IsWarm()
+	if !wasWarm {
 		w.Supervisor.Config = warm.Config{EnterBody: man.EnterBody, MethodBody: man.MethodBody, MethodArg: man.MethodArg}
 	}
 	w.Supervisor.Sink = w.Results.Sink(man)
@@ -217,7 +226,7 @@ func (w *Worker) runOne(ctx context.Context, ref ClaimRef, receipt string) {
 		return
 	}
 
-	if serr := w.Results.WriteSummary(ctx, man, failed); serr != nil {
+	if serr := w.Results.WriteSummary(ctx, man, failed, wasWarm); serr != nil {
 		// Wrote results (if any landed before this point they're already in the
 		// sink) but couldn't signal completion. Leave un-acked: a redelivery
 		// re-drains against the (still warm, unaffected) resident runner and

internal/pool/pool_test.go

@@ -115,8 +115,9 @@ type fakeResults struct {
 }
 
 type writtenSummary struct {
-	man    calexec.Manifest
-	failed []int
+	man     calexec.Manifest
+	failed  []int
+	warmHit bool
 }
 
 func (f *fakeResults) Sink(_ calexec.Manifest) warm.Sink {
@@ -127,13 +128,13 @@ func (f *fakeResults) Sink(_ calexec.Manifest) warm.Sink {
 	return s
 }
 
-func (f *fakeResults) WriteSummary(_ context.Context, man calexec.Manifest, failed []int) error {
+func (f *fakeResults) WriteSummary(_ context.Context, man calexec.Manifest, failed []int, warmHit bool) error {
 	if f.writeErr != nil {
 		return f.writeErr
 	}
 	f.mu.Lock()
 	defer f.mu.Unlock()
-	f.summaries = append(f.summaries, writtenSummary{man: man, failed: failed})
+	f.summaries = append(f.summaries, writtenSummary{man: man, failed: failed, warmHit: warmHit})
 	return nil
 }
 
@@ -257,6 +258,15 @@ func TestWorker_StaysWarmAcrossClaims(t *testing.T) {
 	if call != 2 {
 		t.Errorf("second claim's result call=%d, want 2 (runner state did not persist across claims)", call)
 	}
+	// calque#102: the first claim pays the cold load (warmHit=false); the
+	// second reuses the resident runner (warmHit=true) — this is the exact
+	// signal a submitter needs to report cost.Measured.WarmHit honestly.
+	if results.summaries[0].warmHit {
+		t.Error("first claim's summary reports warmHit=true, want false (it triggered the cold load)")
+	}
+	if !results.summaries[1].warmHit {
+		t.Error("second claim's summary reports warmHit=false, want true (it reused the resident runner)")
+	}
 }
 
 // TestWorker_MismatchedModelClaimIsAckedNotRun: a claim whose Model doesn't

internal/pool/s3.go

@@ -54,16 +54,21 @@ func (r *S3Results) Sink(man calexec.Manifest) warm.Sink {
 }
 
 // poolSummary is the completion record a pool claim writes — deliberately
-// smaller than cmd/warmd's full Summary (no occupancy/enter-seconds
-// bookkeeping here; those belong to the AMORTIZED cost-attribution work,
-// calque#102, tracked separately so this issue doesn't grow to cover it).
+// smaller than cmd/warmd's full Summary (no occupancy bookkeeping here). It
+// carries just enough for a submitter to feed cost.Measured honestly
+// (calque#102): WarmHit tells the submitter whether THIS claim's
+// AcquireSeconds/EnterSeconds should be reported as near-zero (a pool hit)
+// or the pool's own dedicated first-load cost (a miss) — the submitter,
+// not the worker, ultimately builds the cost.Model, since only the
+// submitter knows the run's item count and card-asked-for.
 type poolSummary struct {
-	Failed []int `json:"failed"`
+	Failed  []int `json:"failed"`
+	WarmHit bool  `json:"warm_hit"`
 }
 
 // WriteSummary implements ResultWriter.
-func (r *S3Results) WriteSummary(ctx context.Context, man calexec.Manifest, failed []int) error {
-	body, err := json.Marshal(poolSummary{Failed: failed})
+func (r *S3Results) WriteSummary(ctx context.Context, man calexec.Manifest, failed []int, warmHit bool) error {
+	body, err := json.Marshal(poolSummary{Failed: failed, WarmHit: warmHit})
 	if err != nil {
 		return err
 	}