[robbiemu]

Maple Local already supports registering projectors in its eventing runtime, but its standalone server has no way to load external implementations. Deployments currently need a source patch to populate that registry. This adds repeatable maple start --projector-module /path/to/projectors.mjs flags so domain-specific projectors can ship separately.

The module's default export implements a small versioned contract: { apiVersion: 1, register(registerProjector) }. Registration can be synchronous or asynchronous. The serving process builds a fresh registry under its PID claim before any reset, checkpoint reconciliation, migration abandonment, dirty-store recovery, or chDB open. It reuses that registry in the managed eventing runtime and compiles saved projections before accepting traffic. Background parents hand their PID claim, canonical module paths and reset option to the child; only that child validates modules and prepares the store. Invalid modules, duplicate registrations, and saved projections with missing implementations fail startup.

Modules are explicitly selected trusted local code, with the server's privileges. This does not add package discovery, URL loading, hot reload, or domain-specific projectors. Runtime dependencies should be bundled into ESM .mjs files. The new documentation covers the contract, checkpoint/restart requirements, and trust boundary.

Validation with Bun 1.4.0:

• CLI suite: 663 passed, 19 skipped, 0 failed.
• Eventing core: 38 passed; core typecheck passed.
• Production CLI sources typecheck passed with test sources excluded. The full CLI typecheck reports TS2367 at src/core/release-signature.test.ts:202, which is unchanged from the base commit f73ef32c1.
• Changed-file lint, formatting and whitespace checks passed.
• Full native build passed on macOS ARM64 with chDB 26.7.3. After ad-hoc signing the local test binary, the compiled-binary probe passed: repeated external module flags, OTLP ingestion, ready outbox events, saved projections, detached restart, stable retry identity, startup refusal when the module is omitted, and byte-for-byte preservation of populated stores when invalid modules accompany foreground/background resets or dirty-store wipes. The probe also verifies one registration per serving process under its PID claim and a successful valid background reset. The reset regression was first reproduced against the original PR binary, then passed against the corrected build.

The native probe is also added to the existing Linux native CI job. No existing installation or data migration is part of this change.

Summary by CodeRabbit

• New Features
  • Maple Local can load trusted external event projector modules using repeatable --projector-module options, including in background starts.
  • Modules are checked during startup; invalid modules prevent reset or store-recovery operations from changing the store.
• Documentation
  • Added guidance on configuring projector modules, their registration requirements, restart behavior, and security considerations.

[maple-review-bot]

Maple review

🟢 Confidence 9/10 · safe to merge
Module load sits before chDB and the listener, and the registry reaches the runtime through the LocalEventingProjectors seam the existing tests already provide.
_{quality 100/100 · no findings · tests covered · risk medium · 1/1 new units observable}

Adds a repeatable maple start --projector-module <file>.mjs flag that loads trusted local projector modules, canonicalizes the paths, builds a fresh registry before chDB opens, and forwards the paths to background starts. Contained and safe to merge.

• --projector-module loads repeatable local .mjs projector modules into local mode
• loadProjectorModules builds a fresh registry and refuses startup on invalid or duplicate modules
• The registry reaches the eventing runtime through LocalEventingProjectors before saved projections compile
• Canonical paths are forwarded to detached --background starts

What was checked

• loadProjectorModules runs before acquireChdb and the bind (serve.ts:1483), so a bad module leaves no store behind
• An unregistered projector still fails closed at CompiledProjectionRegistry.compile (registry.ts:171)
• Throwing module code is contained: registry.ts:208 wraps prepare, registry.ts:251 wraps project/decodeOutput

Observability coverage: 1 of 1 changes observable

Change	Kind	Observable	Evidence
startup load of external projector modules	startup step	yes	Runs inside the maple root span with cli.argv (bin.ts:124) and before chDB opens (serve.ts:1483); failures close that span Error

_{5fc50d3 · Updated on every push. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.}

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review.

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: bc90498f-5fe0-4d0a-a457-e15dd745b4f1

📥 Commits

Reviewing files that changed from the base of the PR and between 5fc50d3 and e8ef7cc.

📒 Files selected for processing: 6

• apps/cli/src/commands/server-args.ts
• apps/cli/src/commands/server.ts
• apps/cli/src/server/serve.ts
• apps/cli/test/native-projector-modules.ts
• apps/cli/test/server-args.test.ts
• docs/local-projector-modules.md

🚧 Files skipped from review as they are similar to previous changes: 1

• docs/local-projector-modules.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

Walkthrough

Maple Local can load trusted external ESM projector modules through repeatable --projector-module flags. Startup validates module paths, exports, and registrations before store recovery or reset. The loaded projectors are passed to eventing for foreground and background starts.

Changes: External Projector Modules

Layer / File(s)	Summary
Module contract and loading packages/eventing-core/src/projector-module.ts, packages/eventing-core/src/index.ts, apps/cli/src/server/eventing/projector-modules.ts, apps/cli/test/projector-modules.test.ts, docs/local-projector-modules.md	The public API defines a versioned module contract. The CLI resolves local .mjs files, validates exports and registrations, and creates a projector registry. Unit tests and documentation cover loading, registration, path resolution, and startup failures.
Foreground and background startup wiring apps/cli/src/commands/server.ts, apps/cli/src/commands/server-args.ts, apps/cli/src/server/serve.ts, apps/cli/test/server-args.test.ts, docs/local-mode.md, .changeset/local-projector-modules.md	The start command accepts repeatable module paths and forwards resolved paths and reset options to detached startup. The server loads modules before recovery or reset and provides the registry to eventing.
Compiled-binary verification apps/cli/test/fixtures/projector-module.mjs, apps/cli/test/native-projector-modules.ts, .github/workflows/ci.yml	The native test checks projector output, detached restart behavior, module failures, and reset and recovery behavior. CI runs the probe and collects its temporary directory for failure evidence.

Priority: Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant StartCommand as start command
  participant PathResolver as resolveProjectorModulePaths
  participant Server as startServer
  participant ModuleLoader as loadProjectorModules
  participant ExternalModule as external module
  participant Eventing as eventing layer
  StartCommand->>PathResolver: resolve supplied module paths
  PathResolver-->>StartCommand: return resolved paths
  StartCommand->>Server: start with resolved paths
  Server->>ModuleLoader: load configured modules
  ModuleLoader->>ExternalModule: import and register projectors
  ModuleLoader-->>Server: return projector registry
  Server->>Eventing: provide loaded projectors

Loading

Suggested reviewers: makisuo

Merge Risk: Minimal · up to e8ef7

No unresolved issue identified here prevents merging after normal checks.

Pre-merge checks: 5

Passed checks: 5 passed

Check name	Status	Explanation
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: loading external projector modules in CLI local mode.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 1 potential issue.

[maple-review-bot]

Maple review

🟢 Confidence 9/10 · safe to merge
I traced the parent/child PID-claim handover and the new reset ordering end to end, and the new native probe pins the destructive path byte-for-byte.
_{quality 100/100 · no findings · tests covered · risk medium · 1/1 new units observable}

Moves module validation and store preparation into the detached child and forwards --reset and --projector-module to it, so an invalid module can no longer consume a reset or wipe. The reordering reads correctly against the store-recovery sequence and is safe to merge.

• maple start --background forwards --reset and module paths to the detached child
• The parent spawns the child before any reset, wipe or dirty-store recovery
• A foreground start validates modules under the PID claim before reconciliation or reset
• startServer accepts an already-prepared ProjectorRegistry

Production impact

Production traffic of the changed files (last 7 days)

File	Calls/day	Busiest operations
apps/cli/src/commands/server.ts	23	GET /health 17/day, 0.0% err GET /health 6/day, 0.0% err

What was checked

• PID claim still precedes startDetached, and the child claims it via PID_HANDOVER_ENV (server.ts:1231, :1032)
• ensurePortFree still runs in the parent before the child is spawned (server.ts:1243)
• --chdb-config-file for relative paths is unchanged, since resolveChdbConfigFile returns supplied paths untouched (server.ts:641)

Observability coverage: 1 of 1 changes observable

Change	Kind	Observable	Evidence
external projector module load during maple start	startup step	yes	runs inside the maple root span (apps/cli/src/bin.ts:124); failures print one error: line (bin.ts:130-136)

_{e8ef7cc · Updated on every push. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.}

[Makisuo]

I'm intrigued what you use this for @robbiemu

[robbiemu]

I'm intrigued what you use this for @robbiemu

oh, I’ve just got a self-hosted GitLab setup feeding events into Maple, with custom projectors that turn those into updates for Matrix rooms and threads. I’d been carrying that stuff in my fork, and since my earlier PR got merged I haven't had time to revisit using main instead of my fork until today. I realized I couldn't stop using a custom branch without a loader, and a generic loader obviously is best. this lets me keep them in a separate module and just plug them in at startup.

so yeah I'm basically trying to stop maintaining a whole fork for what is really just configuration. 😅