Implement adaptive capture scheduling and deduplication #73

Merged

lost-rob0t merged 24 commits from agent/issue-20-adaptive-capture-rage into main

2026-08-22 10:52:34 +00:00

lost-rob0t commented

2026-08-22 09:35:39 +00:00

(Migrated from github.com)

Closes #20.

Implements adaptive scheduling, change detection, perceptual deduplication, and bounded overload response through the repository RAGE/TDD workflow.

Implemented behavior

validated capture.cadence_seconds drives the base interval through production composition;
validated capture.change_threshold drives deterministic 64-bit RGB8 perceptual dHash comparison;
active-window/workspace/window-ID changes use one bounded 250 ms debounce candidate, never an event queue;
AdaptiveCaptureFlow binds an already-authorized ApprovedCaptureRequest to scheduling, backend capture, generation validation, perceptual classification, and downstream admission;
not-due work never invokes the capture backend;
stale-generation frames fail before fingerprint/dedup state mutation;
near duplicates in the same generation/config/policy/application/workspace/window context are coalesced and return no frame for OCR/model/downstream work;
generation, policy revision, configuration revision, or normalized metadata-context changes force a fresh observation even for identical pixels;
deterministic 10,000-transition churn coverage proves controller state remains O(1);
existing #8 pipeline ACCEPTED / DROPPED / COALESCED outcomes feed bounded reversible cadence backoff, with no second queue or pressure metric;
documentation now describes configuration, privacy scope, dedup timing, and overload composition.

TDD evidence

Iteration 1 accepted RED: 2460ae320cc6efd52250fa1e7a04133cbb71b2a4, CI 407. Formatting/lint/shell passed; strict Pyright failed specifically because the adaptive controller/hash API did not exist.

Iteration 1 exact green: e60bb0599bac1f9d6f0ac89846b8f89b53101cdd, CI 410.

Iteration 2 accepted RED: 1b824d044438a931d0d004418f1122765c0ddca8, CI 414. Formatting/lint/shell passed; strict Pyright failed specifically because AdaptiveCaptureFlow/AdaptiveCaptureOutcome did not exist.

Iteration 2 exact green: 855eab28d08051966b4701c613778fe480e12a46, CI 416.

Iteration 3 rejected RED: 3d0dc9a6b55fdb6755dca9161f545a7cd9e80046, CI 419, because import sorting failed before behavior. Accepted RED: 5cd6b724a446bd3fb4d3465b14715086ce8d7d6d, CI 420, where formatting/lint/shell passed and strict Pyright failed specifically because apply_submission_feedback was absent. Production head b41d643ca7a8cba2a041644421b525d25c525ade passed CI 421 completely.

Iteration 4 accepted RED: 69599cede2f9b395858d82a8f6051df534a46308, CI 422. Formatting/lint/shell passed; strict Pyright failed specifically because the production capture-settings composition API and inspected controller configuration properties were absent. Production composition maps validated CaptureSettings into the adaptive controller without adding a parallel configuration source.

Full architecture/rejected-alternative/security reasoning remains in rage/issue-20-adaptive-capture.org.

Privacy and resource boundaries

adaptive scheduling never grants capture authority;
no raw screenshot, OCR text, title, URL, command line, secret, provider payload, or bulk frame cache is retained by controller state;
dedup never crosses capture generation, policy, or configuration boundaries;
existing bounded pipeline credits/HWM remain the only bulk queue authority;
overload cannot make policy more permissive or revive stale work;
controller/result representations remain content-redacted.

Final gate

Current exact-head CI must be fully green on both Ubuntu matrices, the canonical ./scripts/check job, and failure-propagation before this draft is promoted or merged.

Closes #20. Implements adaptive scheduling, change detection, perceptual deduplication, and bounded overload response through the repository RAGE/TDD workflow. ## Implemented behavior - validated `capture.cadence_seconds` drives the base interval through production composition; - validated `capture.change_threshold` drives deterministic 64-bit RGB8 perceptual dHash comparison; - active-window/workspace/window-ID changes use one bounded 250 ms debounce candidate, never an event queue; - `AdaptiveCaptureFlow` binds an already-authorized `ApprovedCaptureRequest` to scheduling, backend capture, generation validation, perceptual classification, and downstream admission; - not-due work never invokes the capture backend; - stale-generation frames fail before fingerprint/dedup state mutation; - near duplicates in the same generation/config/policy/application/workspace/window context are coalesced and return no frame for OCR/model/downstream work; - generation, policy revision, configuration revision, or normalized metadata-context changes force a fresh observation even for identical pixels; - deterministic 10,000-transition churn coverage proves controller state remains O(1); - existing #8 pipeline `ACCEPTED / DROPPED / COALESCED` outcomes feed bounded reversible cadence backoff, with no second queue or pressure metric; - documentation now describes configuration, privacy scope, dedup timing, and overload composition. ## TDD evidence Iteration 1 accepted RED: `2460ae320cc6efd52250fa1e7a04133cbb71b2a4`, CI 407. Formatting/lint/shell passed; strict Pyright failed specifically because the adaptive controller/hash API did not exist. Iteration 1 exact green: `e60bb0599bac1f9d6f0ac89846b8f89b53101cdd`, CI 410. Iteration 2 accepted RED: `1b824d044438a931d0d004418f1122765c0ddca8`, CI 414. Formatting/lint/shell passed; strict Pyright failed specifically because `AdaptiveCaptureFlow`/`AdaptiveCaptureOutcome` did not exist. Iteration 2 exact green: `855eab28d08051966b4701c613778fe480e12a46`, CI 416. Iteration 3 rejected RED: `3d0dc9a6b55fdb6755dca9161f545a7cd9e80046`, CI 419, because import sorting failed before behavior. Accepted RED: `5cd6b724a446bd3fb4d3465b14715086ce8d7d6d`, CI 420, where formatting/lint/shell passed and strict Pyright failed specifically because `apply_submission_feedback` was absent. Production head `b41d643ca7a8cba2a041644421b525d25c525ade` passed CI 421 completely. Iteration 4 accepted RED: `69599cede2f9b395858d82a8f6051df534a46308`, CI 422. Formatting/lint/shell passed; strict Pyright failed specifically because the production capture-settings composition API and inspected controller configuration properties were absent. Production composition maps validated `CaptureSettings` into the adaptive controller without adding a parallel configuration source. Full architecture/rejected-alternative/security reasoning remains in `rage/issue-20-adaptive-capture.org`. ## Privacy and resource boundaries - adaptive scheduling never grants capture authority; - no raw screenshot, OCR text, title, URL, command line, secret, provider payload, or bulk frame cache is retained by controller state; - dedup never crosses capture generation, policy, or configuration boundaries; - existing bounded pipeline credits/HWM remain the only bulk queue authority; - overload cannot make policy more permissive or revive stale work; - controller/result representations remain content-redacted. ## Final gate Current exact-head CI must be fully green on both Ubuntu matrices, the canonical `./scripts/check` job, and failure-propagation before this draft is promoted or merged.