A full-featured download manager.
Plugin Hook Runtime Implementation Plan
Status: executable plan for the reviewed
plugin-hook-runtime.md specification. No implementation
step may weaken a normative invariant to make an existing test pass.
1. Outcome and release gate
The change is done only when Electron and Server construct one shared Hook
runtime; the four Hooks execute through the real PluginHost and QuickJS
worker; candidate activation, permissions, DTOs, lanes, finalize recovery, and
post delivery follow H1-H25; the three hash-locked builtins pass real Hook
invocation; and every command in section 10 passes from a clean checkout.
This plan does not copy or cherry-pick PR #2035. Existing code is evidence only.
The locked .moext archives remain supply-chain inputs and builtin source is
not modified.
2. Dependency graph
P0 native/filesystem feasibility + dependency hydration
-> P1 shared schemas/protocol
-> P2 matcher, policy generation, lanes, demand activation
-> P3 additive database v4 + atomic repositories
-> P4a finalize planner/committer/recovery
-> P4b durable post-delivery scheduler
-> P5 shared runtime/startup coordinator + task integration
-> P6 Electron/Server assembly
-> P7 real builtin, compatibility, fault, parity, and full gates
P1 and P2 may proceed in parallel after P0. P4a and P4b may proceed in parallel after their P1/P3 interfaces stabilize. Shell wiring starts only after the core factory and recovery order are tested.
3. Work packages and files
P0 — Feasibility and baseline
- Hydrate the exact
pnpm-lock.yamldependency graph withpnpm install --frozen-lockfile; never usenpx. - Run the current focused Hook/host/finalize/session tests and record pre-existing failures before editing.
- Add a platform filesystem helper under
packages/finalize-fs/only if no existing dependency provides held no-follow handles, file/directory fsync, strong identity, and atomic no-replace install. Its Rust/native API must expose capability-style opaque handles, not arbitrary paths after admission. - Prove file and directory no-replace behavior on Darwin, Linux, and Windows in
adapter contract tests. Unsupported primitives return a typed fail-closed
result; they never fall back to overwrite-capable
rename.
Gate: a feasibility test demonstrates exclusive target creation, symlink-swap rejection, directory install, and durability fault injection before persistence or task code is changed.
P1 — Shared DTOs, protocol, Worker, and SDK parity
Add/update:
src/shared/schemas/plugin-hooks.tssrc/shared/schemas/index.tssrc/shared/types/plugin-hooks.tssrc/core/plugin/host/bridge-protocol.tssrc/core/plugin/host/quick-js-worker.tssrc/core/plugin/host/capability-bridge.ts- adjacent schema/protocol/Worker/bridge tests
Implement strict Zod schemas and inferred types for every enter/exit message,
PluginTaskSnapshotV1, ErrorDescriptorV1, DeliveryEnvelopeV1, effects,
metadata operations, limits, and canonical stable payloads. Every
invocation-scoped message carries invocationId, call-chain ID, and permission
generation. The Worker exposes pre-Hook six-method and post-Hook four-method
ctx.metadata, synchronous read-after-write staging, deterministic Hook exit,
the specified AbortSignal subset, and ctx.delivery.id.
Add compiled SDK 2.0 four-Hook and pinned SDK >=2.1 post-delivery fixtures. If the compatible public SDK minor is unavailable, implementation may continue behind tests but the release gate remains blocked; do not invent unpublishable types and call the contract complete.
P2 — Structured permissions, policy barrier, lanes, and activation
Add/update:
src/core/plugin/permissions/host-pattern.tsand testssrc/core/plugin/hooks/eligibility.tsand testssrc/core/plugin/capabilities/http.tsand redirect/proxy testssrc/core/plugin/host/plugin-lane.tsand testssrc/core/plugin/host/plugin-host.tssrc/core/plugin/host/activation-dispatcher.tssrc/core/plugin/plugin-registry.tssrc/core/plugin/grants/grants-manager.ts- command graph/invoker tests where call-chain propagation enters
Replace both raw regex paths with one parsed manifest-v1 matcher and one shared
conformance corpus. Reject guest-selected HTTP proxies. Candidate discovery
reads enabled registry entries, not active workers; HTTP source matching applies
only to beforeCreate. Hook demand coalesces activation and reactivates recycled
workers.
Create one FIFO lane per plugin for Hooks, commands, lifecycle, and deactivation. Reject self/cyclic call chains before enqueue. Add a monotonically increasing live policy generation and exclusive mutation barrier that closes admission, aborts capability leases, drains/terminates the lane, and then publishes the new enabled/grant/executable state. Idle disposal requires a drained lane and zero capability leases.
P3 — Additive database v4 and atomic repositories
Add/update:
src/core/session/migrations/v4.tssrc/core/session/migrations/v4.test.tssrc/core/session/migrations/index.tssrc/core/session/motrix-database.tssrc/core/session/motrix-database.test.ts- repository interfaces under
src/core/plugin/runtime/
Add only new tables/indexes; do not rewrite task tables:
plugin_finalize_journalsfor plan, artifact identities, phases, quarantine, and cleanup state;plugin_post_deliveriesfor admitted stable payloads, leases, attempts, receipts, permission snapshots, and permanent reasons;plugin_post_quota_ledgerfor atomic row/byte reservation;plugin_post_quota_bucketsfor bounded daily/lifetime/global rollups;- a lifecycle coordination journal if registry state cannot join the SQLite transaction directly.
Expose one transaction that commits task terminal state, task/instance path
updates, task-file rebasing, plugin metadata, journal db_committed, occurrence,
and delivery row or quota tombstone. Foreign keys must not cascade task deletion
into deliveries. Validate persisted JSON on read and quarantine malformed rows.
Migration tests assert the exact schema, fresh install, v3 upgrade, idempotence,
constraint failure rollback, quota reservation, and future-version refusal.
P4a — Finalize plan, file commit, compensation, and recovery
Add/update:
src/core/plugin/finalize/artifact-identity.tssrc/core/plugin/finalize/artifact-mutation-lease.tssrc/core/plugin/finalize/filesystem-adapter.tssrc/core/plugin/finalize/hook-plan.tssrc/core/plugin/finalize/finalize-committer.tssrc/core/plugin/finalize/finalize-recovery.tssrc/core/plugin/hooks/hook-orchestrator.tssrc/core/plugin/hooks/staged-effects.tssrc/core/plugin/hooks/staging-dir.tssrc/core/task/actions/finalize-task.ts- focused unit, integration, and fault-injection tests beside those files
The orchestrator only validates effects and returns an immutable HookPlan. The
committer acquires the task artifact mutation lease, must successfully stop the
engine/Host writers, records strong file/tree identities, writes prepared, and
performs target-local no-replace install. It revalidates identities around every
action and before commit/delete. Replacement output is installed instead of the
original. All mismatch branches preserve bytes and quarantine.
Recovery runs before task producers and handles every adjacent phase layout. Cover direct files, single/multi-file BT, empty/large trees, source==target, case-folding, symlinks/reparse/special files, EXDEV copies, target races, metadata/DB failure, mutation after each phase, compensation failure, and a crash before/after every file action/fsync/journal/transaction.
P4b — Reliable post-Hook delivery
Add:
src/core/plugin/post/delivery-types.tssrc/core/plugin/post/delivery-materializer.tssrc/core/plugin/post/delivery-scheduler.tssrc/core/plugin/post/delivery-retention.tssrc/core/plugin/post/delivery-observability.ts- adjacent deterministic clock/jitter/quota/lifecycle tests
Snapshot candidates under a registry generation lease before the terminal transaction. The database transaction admits a full row or bounded tombstone. The scheduler claims fairly by plugin, uses the specified lease/backoff/breaker, enters the same plugin lane, and records a receipt only for a matching exit. Expiration returns a row to pending; task deletion cannot remove it.
At execution, permissions are creation snapshot intersect current live grants.
Grant revocation aborts active attempts; upgrade marks old digest rows
superseded and never runs old code. Terminal rows compact immediately and all
active/terminal/tombstone row+byte quotas and core reserve limits are enforced
inside the admission transaction.
P5 — Shared runtime, startup coordinator, and task integration
Add/update:
src/core/plugin/runtime/plugin-hook-runtime.tssrc/core/plugin/runtime/startup-coordinator.tssrc/core/plugin/runtime/runtime-factory.tssrc/core/task/create-task-handler.tssrc/core/task/hook-dispatch.tssrc/core/task/occurrences/occurrence-dispatcher.tssrc/core/session/session-manager.ts- associated integration/order tests
One factory owns PluginHost, candidate resolver, lanes, orchestrator,
finalization, occurrence materialization, and post scheduler. beforeCreate
receives the complete validated request and applies role-ordered effects before
persistence. beforeFinalize runs after engine quiescence and before any rename.
Terminal success/error uses the single database transaction; post Hooks never
change terminal status.
The startup coordinator enforces: migrate -> discover/runtime -> register consumer -> finalize recovery -> task/session restore without producers -> delivery/occurrence drain -> open polling/completion producers. Shutdown closes admission, drains within budget, persists leases, and stops workers.
P6 — Electron and Server symmetry
Update:
src/main/index.tssrc/main/ipc/commands.tssrc/main/plugin/capability-host.tssrc/server/index.tssrc/server/ipc/commands.tssrc/server/plugin/capability-host.ts- paired assembly and startup-order tests
Both shells call the same runtime factory and startup coordinator and inject the same instance into create/finalize/error/recovery paths. Remove command-local orchestrator construction. Production startup fails if required database, recovery, delivery, or filesystem primitives are missing; only isolated unit tests may inject a no-op.
P7 — Real acceptance and regression gates
Update/add:
src/core/plugin/host/e2e-builtins.test.tssrc/core/plugin/host/orchestrator.e2e.test.tssrc/core/task/create-task-handler.plugin-hook-e2e.test.tssrc/core/plugin/host/e2e-hook-compatibility.test.ts- reusable local HTTP/TLS test server and fault adapters under existing test helper conventions
Tests must fetch/read the exact archives from scripts/builtins.lock.json, then
assert size, SHA-256, and signature before install. They must invoke the built
bundle through PluginHost/QuickJS:
- url-resolver performs the Commons page/API flow through a real loopback
transport that preserves the authorized URL/Host and returns an independently
accepted
upload.wikimedia.orgURL; - filename-template synchronously reads
ctx.metadata.getAll(), renders nested values, survives idle recycle, and commits a no-clobber file and BT-directory rename.
No fixture callback, registration event, preview command, or source copy counts as builtin Hook acceptance.
4. Implementation boundaries and integration order
Keep the work packages separated by subsystem so their security contracts stay reviewable:
- Protocol and schema covers P1 DTO, Worker, Host, and SDK parity files.
- Host policy covers P2 matching, permissions, lanes, and capability gates.
- Finalize covers
packages/finalize-fs/, P4a files, andfinalize-task.ts. - Post-delivery covers P4b and depends only on the published repository interfaces.
Database migrations and shell integration land after those interfaces are stable. A change that crosses a boundary must update the shared interface and its integration tests in the same change. No package may weaken another package's invariant to simplify integration.
5. Migration, recovery, and rollback
- Database v4 is additive. Startup creates a timestamped pre-v4 backup before migration and verifies it before deleting no data.
- On migration failure, the transaction rolls back and the app remains on v3; no Hook runtime or task producer starts.
- Finalize recovery is forward-only and runs before sessions/producers. Unknown or corrupt journal rows quarantine without deleting bytes.
- A code rollback to a v3-only binary must restore the verified pre-v4 backup; an older binary must refuse a future schema rather than guessing. Post-v4 task changes must be exported/reconciled explicitly before such a rollback.
- Feature rollback inside the v4 binary stops new Hook admission but continues recovery and delivery/quarantine draining; it never abandons a journal.
- Upgrade/uninstall/grant lifecycle operations use the durable barrier so a crash cannot leave old code executable with new grants.
6. Observability and operator proof
Add structured invocation, lane, permission-generation, finalize phase, recovery, delivery lease/retry/dead-letter/quota, and shell startup events using the names/fields in the specification. Redact headers, proxy credentials, secrets, private source metadata, and public-doc absolute paths. Tests assert event parity between Electron and Server and stable error categories.
7. Definition of done by stage
- P1: schema/Worker/Host/SDK field parity and synchronous metadata tests pass.
- P2: one matcher corpus, registry candidate discovery, reactivation, lane, policy-revocation, proxy, and cycle tests pass.
- P3: v4 migration and atomic terminal/delivery/finalize transaction tests pass.
- P4a: all file/directory fault and mutation injection tests pass with no byte loss or overwrite.
- P4b: restart, duplicate, fairness, breaker, quota, lifecycle, and idempotency tests pass.
- P5/P6: one runtime per shell and exact startup/shutdown order tests pass.
- P7: all three locked builtin real Hooks plus SDK 2.0/2.1 fixtures pass.
- Final independent reviewer finds no unresolved correctness, security, data integrity, SDK, or shell-drift defect.
8. Test commands during development
Run the smallest affected ./node_modules/.bin/vitest run <files...> after each package,
then the package cluster after every merge. Native helper changes also run its
format/lint/unit tests. Never hide a red test by weakening assertions or using a
mock in place of the required real QuickJS/HTTP/filesystem boundary.
9. Rollout order
- Land dormant schemas, matcher, lanes, repositories, and migration.
- Land finalize recovery and post scheduler behind the shared factory.
- Wire both shells in one change with parity tests; no one-shell rollout.
- Enable real Hook admission only after startup recovery passes.
- Run builtin/compatibility/fault suites, then all gates.
- Obtain independent final review, fix findings, rerun affected and full gates.
10. Required final commands
./node_modules/.bin/vitest run <all focused Hook/runtime/finalize/post/shell suites>
pnpm run build:builtin
pnpm run check:schema-parity
pnpm run check:file-names
pnpm run check:boundaries
pnpm run lint
./node_modules/.bin/tsc --noEmit
./node_modules/.bin/vitest run
pnpm run build:electron
pnpm run build:server
pnpm run docs:check
Also run the native filesystem package's own tests/build on every supported host available in CI. Exact commands and pass/fail counts belong in the final report; skipped platform evidence remains an explicit residual risk.