Adaptive lock-region controller (Coarse/Medium/Fine, traffic-reactive) #10

New issue

Closed

opened 2026-06-23 08:08:14 +00:00 by sscoble · 1 comment

sscoble commented

2026-06-23 08:08:14 +00:00

Owner

Why

The lock-region is a function of traffic, not a constant (posts#1, Q8). System reacts to load. Three granularities:

Scope	Shape	When
Coarse	per-author queue	cold start, low traffic
Medium	per-author queue + per-post sub-queue	mid traffic
Fine	per-mutation lock, no queueing	high traffic

File

api/locks.go

Controller

Per-author state: {scope enum, queue_depth int, hold_time_p99 time.Duration, throughput_eps float64}
Runs every 1s
Hysteresis to avoid oscillation:
- Coarse → Medium at queue_depth > 50 for 5s
- Medium → Fine at queue_depth > 200 for 5s
- Fine → Medium at queue_depth < 100 for 30s
- Medium → Coarse at queue_depth < 10 for 30s
Symmetric for agents and humans (no special-casing by kind)

Lock interface

type LockRegion interface {
    Acquire(ctx context.Context) error
    Release()
    Scope() LockScope  // Coarse | Medium | Fine
}

Coarse: chan struct{} per author, size 1.
Medium: chan struct{} per author + per-post map[postID]chan.
Fine: sync.Mutex per (author, post) tuple, no queueing.

Acceptance

Controller transitions are recorded in a per-author transition log (visible to VOPR tests)
VOPR: 1000 seeded runs at varying traffic profiles (cold/burst/sustained/low)
Assert: no deadlock, no author starved > 1s, throughput matches expected profile
Assert: scope transitions match the controller's hysteresis rules
go test -race ./... clean

## Why The lock-region is a function of traffic, not a constant (posts#1, Q8). System reacts to load. Three granularities: | Scope | Shape | When | |---|---|---| | **Coarse** | per-author queue | cold start, low traffic | | **Medium** | per-author queue + per-post sub-queue | mid traffic | | **Fine** | per-mutation lock, no queueing | high traffic | ## File `api/locks.go` ## Controller - Per-author state: `{scope enum, queue_depth int, hold_time_p99 time.Duration, throughput_eps float64}` - Runs every 1s - **Hysteresis** to avoid oscillation: - Coarse → Medium at queue_depth > 50 for 5s - Medium → Fine at queue_depth > 200 for 5s - Fine → Medium at queue_depth < 100 for 30s - Medium → Coarse at queue_depth < 10 for 30s - Symmetric for agents and humans (no special-casing by `kind`) ## Lock interface ```go type LockRegion interface { Acquire(ctx context.Context) error Release() Scope() LockScope // Coarse | Medium | Fine } ``` Coarse: `chan struct{}` per author, size 1. Medium: `chan struct{}` per author + per-post map[postID]chan. Fine: `sync.Mutex` per (author, post) tuple, no queueing. ## Acceptance - Controller transitions are recorded in a per-author transition log (visible to VOPR tests) - VOPR: 1000 seeded runs at varying traffic profiles (cold/burst/sustained/low) - Assert: no deadlock, no author starved > 1s, throughput matches expected profile - Assert: scope transitions match the controller's hysteresis rules - `go test -race ./...` clean

sscoble added the

area/api

kind/feature

prio/p0

labels 2026-06-23 08:08:14 +00:00

agent-engineering commented

2026-07-30 21:57:49 +00:00

Closed — implementation already complete ✅

Verified at c2325: all lock controller acceptance tests pass (PromotesUnderContention, DemotesOnIdle, TransitionLog_Records, Starvation_UnderContention, VOPR_Determinism). go test -race clean. Files: locks.go (389 lines), locks_test.go (167 lines). Closed by ticket dispatch system at cycle c2325.

## Closed — implementation already complete ✅ Verified at c2325: all lock controller acceptance tests pass (PromotesUnderContention, DemotesOnIdle, TransitionLog_Records, Starvation_UnderContention, VOPR_Determinism). go test -race clean. Files: locks.go (389 lines), locks_test.go (167 lines). Closed by ticket dispatch system at cycle c2325.