Document threads.v8Flags

[kriszyp]

⊙ Problem

HarperFast/harper#3138 — Add threads.v8Flags to apply V8 flags such as --optimize-for-size to every worker thread adds a configuration setting that applies V8 flags to the whole process before the first worker thread starts. It is meant for constrained deployments that want --optimize-for-size, which Node refuses in NODE_OPTIONS. It has sharp edges a reader must know before using it: implied flags are not applied, it is read once per process, and restart_service does not apply a change.

❓ Your call: Should an expert setting like this be documented in the main options reference, or kept internal for host-manager's use? Documented here, because it is settable by any operator through harper-config.yaml and HARPER_SET_CONFIG, and the restart and implied-flag behavior would otherwise surprise them.

💡 Solution

• reference/configuration/options.md: a v8Flags entry in the threads list, and an "Applying V8 flags" section covering:

  • what it is for, and an example that lists the flag --optimize-for-size implies;

    ❓ Your call: The environment example uses HARPER_SET_CONFIG, as host-manager will, rather than the generally recommended HARPER_CONFIG. A copied HARPER_SET_CONFIG locks the key against later set_configuration changes. Switching is one word.

  • validation (the -- prefix, trimming, set_configuration refusal, startup failure);

  • that runtime application skips implied flags (verified: a worker's heap limit is 536 MB with runtime --optimize-for-size, 515 MB with it from the CLI or with --max-semi-space-size=1 added);

  • that the main thread's isolate is not changed by creation-time flags;

  • when it takes effect (the restart operation on each node, not restart_service), and how to roll it back, including that a THREADS_V8FLAGS value persists in harper-config.yaml.

• reference/configuration/operations.md (restart sentence, after the replicated recipe) and reference/operations-api/operations.md: the set_configuration sections now say restart_service does not apply a threads.v8Flags change.

  ❓ Your call: These say to send restart "to each node in turn". They could add: restart one node and confirm it serves before the rest, since a ---prefixed flag set that aborts V8 can be replicated by set_configuration. One clause.

• release-notes/v5-lincoln/5.4.md: a "Configuration" entry.

✅ Verification

• Behavior claims checked against the harper branch and a live server built from it:
  • the restart operation relaunched the process (new PID) and a worker reported the changed --stack-trace-limit;
  • restart_service left the old value;
  • harper restart against a running harper run instance printed "Harper is already running" and restarted nothing, so these pages name only the restart operation;
  • an unknown flag prints Error: unrecognized flag and is skipped;
  • set_configuration refuses optimize-for-size and leaves the file unchanged.
• npm run build succeeds with no broken links or anchors. prettier --check is clean on the changed files.
• Pre-push review: Codex, Gemini, Cursor Composer, and Harper domain adjudication over five rounds. Findings fixed; one declined as outside this companion: other pre-existing pages describe harper restart as restarting or replicating.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

🤖 Generated with Claude Code

https://claude.ai/code/session_01VKZAtTiprHW8Sp1Ff4hGAZ

Related PRs: #709 overlaps (both add an exception to the set_configuration restart sentence in reference/configuration/operations.md; whichever lands second merges the two)
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,muse,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse; rounds=6; full=2 @ 89acc61}

_{Review-Attention: skim ~2m (decisions: per-node-restart-guidance, expose-isolate-caveat, rollback-single-restart) @ 89acc61}

[gemini-code-assist]

Code Review

This pull request documents the new threads.v8Flags configuration option introduced in Harper v5.4.0, detailing how V8 flags are applied process-wide, validation rules, and the requirement of a full process restart rather than a restart_service for changes to take effect. The review feedback suggests replacing the <VersionBadge> component with plain text when used mid-sentence in prose to maintain consistency.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-724

This preview will update automatically when you push new commits.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.