kandev/docs/plans/watch-task-cleanup/task-07-actions-cache.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
07-actions-cache	Cache Actions observations with bounded expiry	done	7	06-adaptive-discovery	plan.md	REQ-INTEGRATIONS-GITHUB-WORKFLOW-ATTENTION-002	AC-INTEGRATIONS-GITHUB-WORKFLOW-ATTENTION-002.1 AC-INTEGRATIONS-GITHUB-WORKFLOW-ATTENTION-002.2 AC-INTEGRATIONS-GITHUB-WORKFLOW-ATTENTION-002.3 AC-INTEGRATIONS-GITHUB-WORKFLOW-ATTENTION-002.4	../../specs/integrations/system-design/github-workflow-attention.md

Task 07: Cache Actions observations with bounded expiry

Summary

Cache Actions observations with bounded expiry. Implement with TDD and preserve workspace identity.

In scope

Share workflow-run and job observations across batch enrichment and service status/feedback reads. Scope by credential generation and repository; runs also use head SHA, and jobs use run ID plus attempt. Classify each PR separately.

Use 30 seconds for empty, pending, running, unknown, or attention-required data. Use 5 minutes only for nonempty completed data without attention requirements. Keep 512 entries each for runs and jobs, and coalesce concurrent misses. Do not cache errors or change merge/check eligibility. Preserve the existing 4-worker, 5-second batch enrichment budget.

Explicit refresh invalidates relevant outer and Actions cache entries. Prevent in-flight old observations from repopulating after invalidation. Head and credential changes must select fresh entries. Future mutation hooks can reuse this invalidation seam; no approval or rerun UI is added.

Add TestWorkflowAttentionCacheExpiryAndInvalidation to a new workflow_attention_cache_test.go. Cover same-SHA reruns, new run attempts, empty/approval/error results, concurrent callers, credential isolation, different PRs sharing one SHA, explicit refresh, and bounded eviction. Use fake time. Retain the existing workflow attention classification suite.

Update docs/public/integrations.md during implementation to describe the shipped freshness bounds. Keep the public guide unchanged during planning. Run these additional checks after that documentation edit:

node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs

Out of scope

New UI controls, credential policies, global schedulers, and unrelated providers.

Acceptance

• Meet every linked acceptance criterion with deterministic regressions.
• Preserve existing policy, scope, and error-handling contracts.
• Record the expected red test result and passing package results.

Verification

Run from the repository root.

(cd apps/backend && go test ./internal/github -count=1)
git diff --check

Files likely touched

• apps/backend/internal/github/service_pr_watch_batched.go

• apps/backend/internal/github/service_pr.go

• apps/backend/internal/github/service.go

• apps/backend/internal/github/ttl_cache.go

• apps/backend/internal/github/workflow_attention.go

• apps/backend/internal/github/workflow_attention_cache.go

• apps/backend/internal/github/workflow_attention_cache_test.go

• apps/backend/internal/github/workflow_attention_test.go

• docs/public/integrations.md

Dependencies

06-adaptive-discovery.

Risks

Same-SHA results can change. Never freeze a completed workflow collection indefinitely.

Parallelism

sequential

Inputs

• Requirements
• Design
• Source files and existing adjacent tests listed above. New helper/test files are created as needed.

Results

Implemented bounded Actions observation caches shared by batched workflow enrichment and service status, feedback, and watch reads. Run entries are scoped by credential, repository, and head SHA. Job entries are scoped by credential, repository, run ID, and attempt. Completed nonempty observations without attention use a five-minute TTL; empty, changing, unknown, and attention-required observations use 30 seconds. Each cache has 512 entries, singleflight coalescing, and provider-error omission.

Explicit PR refresh invalidates the affected outer status or feedback entry and repository Actions entries. Automatic task subscriptions, reconnects, and retries use passive sync and preserve a completed Actions observation; only a user refresh carries explicit refresh intent and invalidates the relevant entries. Per-key epochs prevent an older in-flight read from repopulating an invalidated cache. Credential changes clear the caches and credential generations remain part of every workspace cache key. Existing workflow classification, fork identity, check state, merge eligibility, and the four-worker, five-second batch budget remain unchanged.

Added TestWorkflowAttentionCacheExpiryAndInvalidation and an in-flight invalidation regression covering same-SHA reruns, attempts, empty and attention data, provider errors, concurrent callers, credential isolation, shared SHAs, explicit refresh, and bounded eviction. The focused test failed before the cache seams existed as expected. Verification passed:

(cd apps/backend && go test ./internal/github -count=1)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs