Skip to content

fix(apps): create AppStorage's kv dir on first write, not on the loop - #24460

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/app-storage-lazy-kv-dir
Oct 27, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/app-storage-lazy-kv-dir

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Stop every app lifecycle event for a storage-enabled app from blocking the gateway event loop on a filesystem mkdir.

AppStorage.__init__ (src/kiro_crew/apps/app_storage.py) created the app's key-value directory with a direct self._kv_dir.mkdir(parents=True, exist_ok=True). The constructor is invoked by the synchronous build_app_context factory (src/kiro_crew/apps/context.py), which the hook-context builders — LifecycleDispatcher._build_context and hooks_integration._build_app_context_from_info — call from coroutines on the gateway event loop. So every lifecycle event (enable, gateway boot, disable, gateway shutdown) for an app granted the storage permission ran a blocking mkdir on the loop.

Why this change

The reporter (IngridMorstrad) needs the AppStorage kv-dir create off the event loop: it is the last constructor-time mkdir on the build_app_context path, the direct sibling of the data-dir create already fixed in #24359. This is a correctness fix for a shared-latency bug — it does not change any default, UI, output, or the storage API; a storage-enabled app behaves exactly as before, the directory is just created on the first write instead of at construction. No user who did not ask for it sees any behaviour change. I matched the lazy-create-on-first-write pattern the sibling JobStore already uses rather than adding an asyncio.to_thread hop, because it is the smaller change and keeps build_app_context synchronous.

Why it matters

While that mkdir waits on a slow or contended data disk, every other session and request served by the gateway waits with it. It is the direct sibling of the data-dir create fixed in #24359; that PR moved the data dir off the loop but deliberately left the AppStorage kv dir, because fixing it needs a decision about where the store's directory contract lives (its constructor is sync and has many sync callers, including tests).

Not a goal

  • No change to the storage permission model — key validation, path-traversal / DOS-device containment, atomic-write behaviour and directory/file modes all stay byte-identical in behaviour.
  • Not re-architecting build_app_context into an async factory; the constructor stays sync.

What changed (motivation → approach → change)

  • Symptom: a blocking mkdir runs on the event loop on every lifecycle event for a storage-enabled app.
  • Root cause: the directory is created eagerly in AppStorage.__init__, and the constructor runs on the loop via the sync factory.
  • Approach: two patterns exist for this store family — (a) lazy-create on first write inside the store's own I/O, or (b) an asyncio.to_thread hop in the async callers. I matched (a), because the nearest sibling store already uses it: JobSDK's JobStore (also built in build_app_context from the app's data_dir, also permission-gated) does not mkdir in its constructor — it creates the dir inside JobStore.write, and its reads tolerate a missing dir. This keeps build_app_context sync and touches only AppStorage, the smallest change.
  • Change: removed the mkdir from AppStorage.__init__ and made the identical Path.mkdir(parents=True, exist_ok=True) call at the top of set (the only write path). The read paths already treat a missing directory as empty: get/delete gate on path.is_file() and list_keys returns [] when self._kv_dir is not a directory.

Permissions are unchanged because the create is the exact same plain Path.mkdir call the constructor used, and it runs before atomic_write touches the tree. atomic_write would otherwise create a missing parent owner-only (0700) inside the data home, but it finds the directory already present and leaves an existing directory untouched, so the kv dir keeps the mode it has today.

Backwards compatibility

Compatible: nothing that works today stops working. The public AppStorage API (get/set/delete/list_keys) is unchanged; only the moment of directory creation moves from construct-time to first-write. Callers that construct the store and then read see an empty store (as before); callers that write see the directory created on that write.

Removes nothing: no path, record, key or function is removed, renamed or tightened — the only observable change is that <app>/data/kv does not exist until the first set instead of at construction, which every read path already handles as empty.

Tests

test/test_app_storage_kv_dir_off_loop.py (new):

  • test_build_app_context_does_not_create_the_kv_dir — building the context via the real on-loop factory records no kv mkdir and leaves the dir absent (red on origin/main, where the constructor mkdirs it on the loop thread).
  • test_first_set_creates_the_kv_dir — the first set creates the dir and the value round-trips.
  • test_first_set_creates_the_kv_dir_with_the_prior_permissions — the lazily-created dir's mode equals a plain Path.mkdir's mode in the same tree (pins the permission model).
  • test_reads_tolerate_a_missing_kv_dir — get/list_keys/delete behave as empty before the dir exists.

test/test_app_context_cov80.py updated: the stale assert (tmp_path / "kv").is_dir() right after build_app_context encoded the old on-construct behaviour; it now asserts the dir is absent after the build and present after the first set.

Proof: PROVEN the new off-loop/first-write tests fail with the production hunks reverted (head 8a98d0f)

Manual verification

N/A — unit coverage sufficient. The reproduction (a Path.mkdir thread probe over the real build_app_context path) is captured by the off-loop test.

Related Issues

Closes #24358

Sibling sweep

Swept: grep -rn "mkdir" src/kiro_crew/apps/*.py for stores that mkdir in a constructor reachable from the sync build_app_context factory.
Sibling: src/kiro_crew/apps/job_sdk.py:JobStore — not affected — it already creates its dir lazily in JobStore.write, which is the pattern this PR adopts.
Sibling: src/kiro_crew/apps/hooks_integration.py / src/kiro_crew/apps/lifecycle.py — not affected — the sibling data-dir create was already moved off the loop in #24359.

Pattern harvest

Not generalizable: this is a one-off — the specific store (AppStorage) was the last constructor-time mkdir on the build_app_context path; the sibling stores already create lazily or were fixed in #24359.

Checklist

  • At most two commits (one here), Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 26, 2026
@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 5bb1f1b044305d42f4b73618a460181f28c799ee touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 5bb1f1b044305d42f4b73618a460181f28c799ee — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (2 items) — 2 justified

Intent: stop lifecycle events for an app with the storage permission from blocking the gateway event loop on a mkdir (#24358). This is a FIX.

  1. Building an app's context no longer creates its <app>/data/kv directory, so a fresh app has no directory until it stores something — justified
  2. An app's first stored value creates the kv directory with the same mode as before, as JobStore.write already does in job_sdk.py:334 — justified

[FIRST-PRINCIPLES-REVIEWED] 5bb1f1b

Description read

[DESCRIPTION-READ] 059fd708a878beac73e10e2906cbb7be4bdd3def5d6ef8a71b3e437b6d776464

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5bb1f1b044305d42f4b73618a460181f28c799ee and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5bb1f1b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5bb1f1b044305d42f4b73618a460181f28c799ee false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5bb1f1b044305d42f4b73618a460181f28c799ee — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5bb1f1b

Verdict parsed from the review's SHA-scoped output markers for commit 5bb1f1b044305d42f4b73618a460181f28c799ee.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5bb1f1b044305d42f4b73618a460181f28c799ee false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 5bb1f1b044305d42f4b73618a460181f28c799ee — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The lazy create matches JobStore, every read path already handles a missing directory, and nothing outside app_storage.py reads data/kv.

[DESIGN-REVIEWED] 5bb1f1b

Description read

[DESCRIPTION-READ] d331b9129bf0a8b8a1b29fa2f0ace9f0c3f2074d1692bc30305e6a64d8208efb

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 26, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/app-storage-lazy-kv-dir branch from 8a98d0f to 2182830 Compare October 26, 2026 12:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 26, 2026
@chenmingwei23
chenmingwei23 marked this pull request as ready for review October 26, 2026 13:43
@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 26, 2026 13:43
@chenmingwei23
chenmingwei23 force-pushed the fix/app-storage-lazy-kv-dir branch from 2182830 to fc4eda4 Compare October 26, 2026 15:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 26, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/app-storage-lazy-kv-dir branch from fc4eda4 to 8a96907 Compare October 26, 2026 18:19
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 26, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/app-storage-lazy-kv-dir branch from 8a96907 to 6807f2e Compare October 26, 2026 21:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 26, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 26, 2026
AppStorage.__init__ ran self._kv_dir.mkdir() directly. The constructor is
invoked by the sync build_app_context factory, which the hook-context
builders call on the gateway event loop, so every lifecycle event for a
storage-enabled app ran a blocking mkdir on the loop.

Move the create to the write path (set), the pattern the sibling JobStore
already uses: JobStore.write mkdirs, and its reads tolerate a missing dir.
AppStorage's reads already do too (get/delete gate on is_file, list_keys
returns [] when the dir is absent). The create uses the identical
Path.mkdir call, so the dir keeps the same mode; atomic_write finds it
present and leaves it untouched, so the permission model is unchanged.
@chenmingwei23
chenmingwei23 force-pushed the fix/app-storage-lazy-kv-dir branch from 6807f2e to 5bb1f1b Compare October 27, 2026 02:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 27, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 27, 2026 04:09

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: AppStorage creates its kv directory on the first write instead of in the constructor, with tests.

@KiroCrewCaptain
KiroCrewCaptain merged commit 144978b into main Oct 27, 2026
112 of 118 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/app-storage-lazy-kv-dir branch October 27, 2026 04:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(apps): AppStorage creates its kv dir on the event loop

2 participants