Skip to content

refactor(shared): establish lazy runtime loader foundation#99261

Merged
RomneyDa merged 1 commit into
mainfrom
refactor/lazy-runtime-foundation
Jul 3, 2026
Merged

refactor(shared): establish lazy runtime loader foundation#99261
RomneyDa merged 1 commit into
mainfrom
refactor/lazy-runtime-foundation

Conversation

@RomneyDa

@RomneyDa RomneyDa commented Jul 2, 2026

Copy link
Copy Markdown
Member

Related: #98748

What Problem This Solves

Resolves the first dependency in the lazy dynamic-import memoizer consolidation: callers need one well-tested cache owner before the repository can migrate repeated module-level promise variables in reviewable batches.

This is PR 1 of 6. It intentionally limits migration to the five representative lazy loaders in src/library.ts; the remaining core, gateway, channel, and plugin batches will follow separately.

Why This Change Was Made

Generalizes the existing lazy promise cache with explicit inspection and clearing, while preserving direct cached-promise identity and selectable rejection caching. The higher-level lazy runtime helpers delegate to that cache and retain sticky dynamic-import rejection behavior.

Only src/library.ts adopts the new function API in this foundation PR.

User Impact

No intended user-visible behavior change. Maintainers get the canonical lazy runtime primitive required for smaller follow-up deduplication PRs without changing module boundaries or publishing new Plugin SDK exports.

Evidence

  • node scripts/run-vitest.mjs src/shared/lazy-promise.test.ts src/shared/lazy-runtime.test.ts src/library.test.ts — 3 files, 10 tests passed across 2 shards.
  • Core production typecheck passed with node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo.
  • Blacksmith Testbox tbx_01kwjkfh0kb96nsja4bck61zz3pnpm build and pnpm check:import-cycles passed; 0 runtime value cycles. Actions run: https://github.com/openclaw/openclaw/actions/runs/28628654780
  • Fresh Codex autoreview — clean, no accepted/actionable findings, 0.97 confidence.
  • Scope proof — 5 files changed, +104/-48 lines.

Series

  1. Foundation — this PR
  2. Core leaf and infrastructure loaders
  3. Core gateway and stateful runtime loaders
  4. Discord, Slack, and Telegram loaders
  5. Matrix and remaining channel loaders
  6. Provider/utility plugins and final enforcement guard

@openclaw-barnacle openclaw-barnacle Bot added size: S maintainer Maintainer-authored PR labels Jul 2, 2026
@clawsweeper

clawsweeper Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 2, 2026, 7:57 PM ET / 23:57 UTC.

Summary
The branch adds lazy-promise function and inspection APIs, delegates lazy-runtime helpers to the shared promise loader, adds focused tests, and migrates five src/library.ts dynamic-import memoizers.

PR surface: Source +2, Tests +54. Total +56 across 5 files.

Reproducibility: not applicable. as a bug reproduction: this is an internal cleanup refactor. Current-main source inspection does confirm the cleanup target, including separate lazy-runtime cache ownership and five manual library facade memoizers.

Review metrics: 1 noteworthy metric.

  • Public lazy-runtime SDK exports: 0 added, 0 removed. The PR keeps the public plugin SDK lazy-runtime subpath enumerated, limiting plugin API compatibility risk.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #98748
Summary: This PR is a bounded implementation candidate for the open maintainer cleanup issue; the broader draft reference PR overlaps but is not merged or currently viable as a superseding target.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • none.

Next step before merge

  • No automated repair is appropriate: this protected maintainer PR has no concrete patch defect, so maintainers should complete normal exact-head review and decide whether to land the bounded first batch.

Security
Cleared: Cleared: the diff is a local TypeScript helper/test refactor with no dependency, lockfile, workflow, permission, secret-handling, or downloaded-code change.

Review details

Best possible solution:

Land this bounded foundation after ordinary maintainer review, while keeping the canonical tracker and broader draft available for follow-up migration batches.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is an internal cleanup refactor. Current-main source inspection does confirm the cleanup target, including separate lazy-runtime cache ownership and five manual library facade memoizers.

Is this the best way to solve the issue?

Yes: delegating lazy-runtime caching to the existing lazy-promise owner and migrating one bounded facade batch is the narrow maintainable first step. The broader repository-wide migration remains better handled in follow-up batches rather than forcing the draft reference implementation into this PR.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e701dc76b060.

Label changes

Label justifications:

  • P3: This is a low-risk internal maintainability refactor with no intended user-visible behavior change.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Not applicable: this is a maintainer-labeled internal refactor PR, so the external contributor real-behavior proof gate does not apply.
Evidence reviewed

PR surface:

Source +2, Tests +54. Total +56 across 5 files.

View PR surface stats
Area Files Added Removed Net
Source 3 45 43 +2
Tests 2 59 5 +54
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 5 104 48 +56

What I checked:

  • Protected live PR state: Live PR metadata shows this PR is open, authored by RomneyDa, labeled maintainer, mergeable/CLEAN, and carrying the current P3 ready-for-maintainer-look state, so conservative cleanup should not auto-close it. (66731b504bcc)
  • Current main still has separate lazy-runtime cache ownership: Current main createLazyRuntimeSurface still owns its own cached promise and does not delegate to createLazyPromiseLoader, so the central PR change is not implemented on main. (src/shared/lazy-runtime.ts:6, e701dc76b060)
  • Current main still has the library memoizers this PR migrates: Current main src/library.ts still declares five module-level runtime promise caches and loader functions for the public facade imports. (src/library.ts:32, e701dc76b060)
  • PR implementation preserves sticky lazy-runtime rejection caching: The PR head makes lazy-runtime helpers delegate to createLazyPromiseLoader with cacheRejections: true, matching the old sticky dynamic-import rejection behavior while adding peek/clear controls. (src/shared/lazy-runtime.ts:16, 66731b504bcc)
  • Plugin SDK boundary remains enumerated: The public Plugin SDK lazy-runtime subpath still enumerates only lazy-runtime helper exports, so the shared helper re-export does not automatically broaden the public plugin API surface. (src/plugin-sdk/lazy-runtime.ts:4, e701dc76b060)
  • Latest shipped release lacks the central change: The latest release tag still has the separate lazy-runtime cache owner and manual library memoizers, confirming this PR is not redundant with shipped behavior. (src/shared/lazy-runtime.ts:6, e085fa1a3ffd)

Likely related people:

  • steipete: GitHub path history shows steipete introduced and iterated the lazy-runtime helper family used by core and Plugin SDK callers. (role: feature-history owner; confidence: high; commits: 9648e7fecb28, 795f1f438b1d, 39a8dab0da60; files: src/shared/lazy-runtime.ts, src/plugin-sdk/lazy-runtime.ts)
  • vincentkoc: GitHub path history shows recent work on the lazy-promise option surface that this PR reuses and extends. (role: recent area contributor; confidence: medium; commits: 884a6a113ccf; files: src/shared/lazy-promise.ts)
  • RomneyDa: RomneyDa authored the canonical cleanup issue, the broader reference implementation, and this bounded foundation PR, making them a routing contact for the series direction. (role: cleanup series owner; confidence: medium; commits: 66731b504bcc, f756733f7088; files: src/shared/lazy-promise.ts, src/shared/lazy-runtime.ts, src/library.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 2, 2026
@RomneyDa
RomneyDa merged commit 5458e31 into main Jul 3, 2026
134 of 140 checks passed
@RomneyDa
RomneyDa deleted the refactor/lazy-runtime-foundation branch July 3, 2026 00:25
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintainer Maintainer-authored PR P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: S status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant