Skip to content

Dcarney/7880 internal build - #8362

Merged
50 commits merged into
mainfrom
dcarney/7880-internal-build
Nov 11, 2026
Merged

50 commits merged into
mainfrom
dcarney/7880-internal-build

Conversation

@dcarney-cf

Copy link
Copy Markdown
Contributor

No description provided.

dbezhetskov and others added 30 commits November 11, 2026 06:52
The zygote Worker that evaluates top-level code for the startup
snapshot reports failures into its own ErrorReporter, but a
KJ exception thrown while it compiles, evaluates or serializes still
propagates out of factory_new_worker() and fails the real Worker.

Catch it around the zygote's script and Worker construction and log
it at INFO like the ErrorReporter case, so a snapshot that cannot be
produced only costs the snapshot.
Pin the bindings object (`env`) into the snapshot in the zygote and take
it out of the snapshot in the Worker started from it, instead of
building a fresh one.

The zygote compiles every binding into env. The object a binding
compiles to is a description that each request resolves through its own
IoContext, so creating it does no I/O.

A Worker started from the snapshot compiles nothing: compileGlobals()
returns early, while ctx.exports, built for the real Worker after the
zygote has run, opts out of that and is always compiled.

The kinds whose objects cannot transfer keep a Worker out of the
pipeline in supportsStartupSnapshot(), logged at INFO.
Store the resolved main-module namespace object into snapshot.
In real worker, recover it instead of resolving the module
namespace again.
Pin each resource type's memoizedConstructor and
contextConstructor materialized templates into the snapshot and record
its snapshot index in SnapshotArtifact.

We rely on the resource types being iterated in the
same order during both the snapshot creation and restoration passes.
Since both passes run within the same binary, this ordering is expected
to remain stable.

A START_FROM_SNAPSHOT isolate then repopulates both slots after
instantiating its type wrapper, before any context is created.
Every WD wrapper carries one aligned-pointer internal field,
WRAPPABLE_TAG_FIELD_INDEX, holding the address of WORKERD_WRAPPABLE_TAG
or WORKERD_RUST_WRAPPABLE_TAG. V8 cannot serialize a non-empty aligned
pointer without a SerializeInternalFieldsCallback, and the address is
process-specific anyway, so the serializer emits the marker's value and
the deserializer maps it back to the marker's address.

The callbacks run inside V8, which is built without exceptions, so they
only count what they cannot handle; createSnapshotBlob() and
newContextWithWrapper() raise those counts afterwards.
Serialize part:
  * Clone all live wrappables right before taking the snapshot
and store the clones in the snapshot artifact so they can be used to
create additional clones later.
  * For each clone, store its cppgc shim pointer as a key to identify
the corresponding JS wrapper during serialization + its tag.
  * Emit the clone's index in the snapshot artifact as serialization
data for the corresponding JS wrapper.

Deserialize part:
  * Preallocate cppgc shims that own C++ wrappables before deserializing
the context, since allocations are not allowed inside the
deserialization callback.
  * Link the preallocated cppgc shims to their corresponding JS wrappers
inside the deserialization callback.

snapshotClone() is virtual, so a subclass that does not override it
inherits its base's clone. Attaching that clone to the subclass's
restored wrapper would put a base instance under the subclass's tag
and abort the first unwrap in the Worker started from the snapshot.
Recording the live wrappables compares the clone's type name with the
original's and fails the zygote instead, so that such a Worker starts
without a snapshot.
Cover API types that commonly appear in snapshots but carry little or
no C++ state:

  * stateless module/singleton objects that are safe to recreate from
    scratch (BufferUtil, CryptoImpl, UtilModule, EntrypointsModule,
    node process/async-hooks/timers/sqlite/zlib modules, rtti,
    sockets, tracing, unsafe, ...);
  * simple value holders cloned field-by-field (Headers, TextEncoder,
    filesystem and messagechannel objects, legacy URL).

Types with substantial runtime state, such as stream internals and actor
state, intentionally remain without snapshotClone.
A DurableObjectNamespace binding owns its ActorIdFactory, so
transferring the binding through a startup snapshot needs a plain-data
copy of the factory, made and used outside any isolate or IoContext.
Add cloneForSnapshot() with a default of none, which keeps a Worker
whose factory cannot be copied off the pipeline, and implement it for
workerd's ActorIdFactoryImpl. Unlike cloneWithJurisdiction(), the copy
carries the predictable-mode counter over, so that an ID the zygote's
top level minted is not minted again by the Worker started from the
snapshot.
The object a binding compiles to is a description that each request
resolves through its own IoContext: a channel number, names and flags.
Creating it does no I/O, so it can be created in the zygote and
transferred like any other live object. Give Fetcher, KvNamespace,
R2Bucket, WorkerQueue, AnalyticsEngine, Hyperdrive,
ColoLocalActorNamespace, DurableObjectNamespace, DurableObjectClass,
DurableObjectId and WorkerLoader a snapshotClone() that copies that
description and returns none when the object is bound to one IoContext
instead (a live channel or factory, a stub minted per request) or has
registered a connect override on the zygote's global scope, which the
restored Worker's fresh global scope would lack. The ctx.exports
loopback stubs and ExtendedFetcher opt out explicitly, and
WorkerdDebugPortConnector is stateless.
The zygote bundles the bootstrap's JS objects (require(), primordials, the
compatFlags/autogates/utils objects and the require() cache) into one
object and pins it into the snapshot, recording the index in the
SnapshotArtifact. A worker started from the snapshot rebuilds its
BootstrapState from that object instead of running the bootstrap scripts
again.

The index is recorded rather than fixed: the object is pinned after the
bindings scope and the main-module namespace, which only modular workers
pin, and it is not pinned at all when the zygote runs without the
per-isolate bootstrap.
By default V8 leaves the read-only space extensible for a
SnapshotCreator isolate, and CreateBlob() promotes the zygote's
AccessorInfo and InterceptorInfo objects into it. Those objects carry
external pointers (JSG getter/setter/interceptor callbacks). The next
zygote built in the same process has to serialize that read-only space
as well, but its external_references table only holds the callbacks it
registered itself, so its CreateBlob() fails with "Unknown external
reference" on the foreign callbacks.

The flag is only set in builds without multiple pointer-compression
cages: there jsg::newIsolateGroup() falls back to the default group, so
every isolate in the process shares one read-only heap. With multiple
cages each zygote owns its group and read-only heap, and what it
promotes travels inside its blob, so the default promotion stays on.

The flag is set unconditionally rather than under the STARTUP_SNAPSHOT
autogate. V8 folds every non-default flag into the hash it stamps on
code caches, and the embedded compile caches are produced at build time
by gen-compile-cache through this same V8System::init(). A flag that
depended on the autogate would make the caches match only one of the
two runtime configurations and be rejected (kFlagsMismatch) in the
other; gating the generator the same way would only move the mismatch
to the default configuration. V8 consults the flag only for
serializer-enabled isolates, so ordinary isolates are unaffected.
supportsStartupSnapshot() now also requires the typescript_implemented_streams
compatibility flag, next to the existing python / ScriptSource / wasm exclusions.

With the C++ streams implementation, a ReadableStream whose pull() or start()
is still pending when top-level evaluation ends leaves a C++ promise
continuation reachable from the context: jsg::Promise::then creates a
v8::Function whose callback is a per-functor template instantiation that is
not in the external-reference table and whose FunctionTemplateInfo data is a
JS object.

The flag is experimental without an enable date, so the pipeline currently
runs only for workers that opt in explicitly. No API surface changes.
…ers propagate

A constructor template restored from the snapshot still intercepts
property access but the C++-side ResourceWrapper never register members
in this isolate, so its wildcardHandler member is still kj::none.

registerInherit() reads that member to propagate a parent's
JSG_WILDCARD_PROPERTY interceptor to subclass templates built fresh
in the restored isolate (e.g.DurableObject inheriting from Fetcher),
and silently skipped it.
V8 does not install certain built-in properties in an isolate being
snapshotted, such as Error.stackTraceLimit, Iterator.concat,
Iterator.zip, and Iterator.zipKeyed.
The zygote's top-level code detects that these properties are missing
and installs workarounds, which are then baked into the snapshot.
During deserialization, V8 unconditionally installs these properties,
causing a failure if they are already present.

We divide these properties into two groups to handle them:

1. Properties that can be preinstalled in the zygote, used by top-level
   code, removed before creating the snapshot, and then reinstalled in
   a newly created context. For example, Error.stackTraceLimit.
   This behavior matches that of Node.js

2. Properties that cause the zygote to throw if its top-level code
   attempts to access them, such as Iterator.*. The access is also
   recorded on the isolate, so a top level that catches the error, or
   lets it reject a promise, still fails the zygote before the snapshot
   is created instead of baking its wrong feature test in.

The test uses new startedFromStartupSnapshot(), added here to the
experimental workerd:unsafe module.
Pin every instantiated ModuleInfo handle (module, source object,
mutable exports, synthetic value) into the context snapshot at
PREPARE_SNAPSHOT, recording (specifier, type, kind) -> AddData index in
SnapshotArtifact::moduleRecords. At START_FROM_SNAPSHOT, after
compileModules() re-registers the entries, overwrite each one with the
baked instance so runtime import()/require() resolve to the same module
graph the baked main module evaluated against (single Buffer.prototype,
etc.).
Listeners registered by zygote top-level code via addEventListener()
live in the C++ EventTarget listener map. The fresh
ServiceWorkerGlobalScope attached by newContext() at load discards the
zygote's map, so the baked listeners were silently lost.

PREPARE: EventTarget::forEachSnapshotListener() enumerates the JS
listeners in per-type insertion order (the on<type> attribute
trampolines are skipped: their identity is synthesized and cannot be
replayed; a listener with a `signal` option is rejected as an
unsupported snapshot case, so the Worker starts without a snapshot).
The Worker constructor pins each listener's identity object into the
snapshot and records (type, identityIndex, once) in
SnapshotArtifact::listenerRecords, right after
removeRestoreTimeGlobalsBeforeSnapshot() and before clear() drops the
zygote global's listener map. Collection happens at the io layer
because jsg cannot see api::EventTarget; the records travel into the
artifact through createSnapshotBlob().

LOAD: the Script constructor, once the module context exists, calls the
baked global addEventListener for every record, which re-derives the
callback (plain fn vs handleEvent, receiver binding, once) exactly as
the zygote registration did. The identity objects live in the snapshot
heap, so their closures and module state stay shared with the baked
module graph.
The zygote that evaluates a Worker's top-level code for the startup
snapshot runs without a V8Inspector, and when the snapshot is used the
Worker's own isolate never evaluates that code. With an inspector
attached, DevTools therefore saw none of the top level's console output
and could not stop at its breakpoints.

Decide the inspector policy before the snapshot block and run the zygote
only when no inspector is configured, by --inspector-addr or by the
Worker's enable_nodejs_inspector_local_dev flag. With an inspector the
Worker starts without a snapshot, as before the pipeline existed.
The zygote that evaluates a Worker's top-level code for the startup
snapshot logs like any Worker: under ConsoleMode::STDOUT its console
output and process.stdout writes go straight to the process's stdout
and stderr. When the snapshot then fails, the Worker
evaluates the top level again and every line is printed twice.

Hold the zygote's lines on its Worker::Isolate instead. The factory
flushes them once the snapshot is accepted, so top-level code prints
exactly once whichever isolate's run counts, and drops them with the
zygote otherwise. Isolate::logWarning follows the same rule.

The new js_test runs `workerd test` on two Workers, one that starts from
the snapshot and one that falls back, and checks that every top-level
line appears once, with and without --inspector-addr.
…recorded

Right before taking a snapshot we build a map with CppgcShim addresses
as keys to restore js wrapper -> cppgc shim -> C++ Wrappable relation.
However, during GC, user-defined JS functions can be run and break
the map.

The zygote now runs JavaScript only while its context is still a normal
one. Worker::Worker calls settleFinalizationRegistriesForSnapshot() right
after the top level, before anything is recorded: microtask checkpoint,
kept objects cleared, a full GC, every task V8 posted, round after round
until a GC posts nothing. The callbacks run without an IoContext and
under the startup limits, as at request time; an exception in one is
reported as an uncaught exception, as at request time; a chain that
does not settle within eight rounds fails the zygote.

After the record, we collect what destroying the graph released
and drains the cleanup tasks under a DisallowJavascriptExecutionScope:
V8's task pops each cleared cell before calling the callback, and the
call throws instead of running, so the dirty list empties without a
JavaScript frame. The targets of such cells were held by C++ state the
snapshot does not carry; rather than drop their cleanups silently, a
zygote with any fails and the Worker starts without a snapshot. A
temporary message listener counts the refused calls.

WrappablesSerializeMetadata also roots every recorded shim with a
cppgc::Persistent, so a recorded address cannot be reused whatever runs
later so the key's uniqueness no longer depends on the order of steps.
A zygote whose top level failed (a parse error, an uncaught exception, a
startup limit) still ran the rest of the PREPARE path: the per-isolate
bootstrap stash in a KJ_DEFER, clear() and createSnapshotBlob().

The Worker constructor now records a top level only when it ran to
completion, with the bootstrap stash as the last record step, and throws
before anything is serialized when impl->permanentException is set.
startup-snapshot-wrappables-test starts case Workers whose top level leaves
JSG objects reachable and checks, at request time, that they kept their
state and still work: Headers and URL (legacy and url_standard) through
their snapshotClone(), TextEncoder, crypto, crypto.subtle and navigator as
stateless types, and the text/data/JSON bindings baked into env. Further
cases cover garbage collection before and after the snapshot, capability
bindings the zygote compiled into env (service, RPC entrypoint and Durable
Object namespace, the latter two going through the wildcard property
handler of the restored Fetcher template and of a subclass), and the
Workers that must start without a snapshot: an AbortController or a
URLSearchParams kept at the top level, and a Worker without
typescript_implemented_streams.

Two limits surfaced while writing it. A snapshot-creator isolate gets no V8
extensions, so under --expose-gc the zygote has no gc(); the gc case falls
back to external memory pressure there. And the module scope of node:fs
reaches UrlUtil, a Rust JSG resource, which has no snapshot transfer, so the
fs case is a known fallback until Rust resource types have one.
snapshot-test.c++ gains an isolate type with three resource types, one
stateless, one with a snapshotClone() and one with neither, and drives a
zygote the way Worker::Worker does: serializer callbacks on the context,
a top-level script, restore-time globals removed, createSnapshotBlob().
An isolate built from the artifact then checks that the stateful
object's state and the stateless object came through, that an object the
context no longer reached at CreateBlob() was dropped from the artifact,
that a reachable untransferable type fails the zygote while an
unreachable one does not, that a subclass inheriting its base's
snapshotClone() fails the zygote instead of transferring as its base,
and that verify() and releaseSlotsWithChecks() raise what the V8
callbacks could only record, including a slot the deserializer never
linked.
startup-snapshot-bindings-test captures a service stub and a Durable
Object namespace and ID at module scope and uses them at request time,
as libraries and user code commonly do (`const rpc = env.RPC`,
`drizzle(env.DB)`); an RPC method taken off a stub, a wrapped binding
and a cryptoKey binding fall back.
docs/startup-snapshot.md walks through the pipeline end to end: when the
zygote runs, what it does before and inside createSnapshotBlob(), what the
Worker started from the snapshot restores and in which order, what travels
in the SnapshotArtifact, how to make a type transferable, what happens on
each kind of failure, how console output is deferred, and which tests cover
what. The root AGENTS.md links it from "Where to Look" and "Other
Documentation".
The zygote's errors said "snapshot PoC:"; they now say "startup
snapshot:". Also remove a temporary INFO log from
settleFinalizationRegistriesForSnapshot().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fixes the startup-snapshot commits needed on current main:
- KJ_IF_SOME inside JSG_WITHIN_CONTEXT_SCOPE lambdas now reads as a
  dangling else, so stashPerIsolateBootstrapForSnapshot() tests the
  Maybe directly and removeRestoreTimeGlobalsBeforeSnapshot() checks
  restoreTimeGlobalUsed before entering the context scope.
- Drop an unused local in bootstrapFromScripts().
- snapshot-test and the guide still called
  WrappablesSerializeMetadata::verify(), since renamed
  dropUnreachableWrappables().
- clang-tidy: a redundant `typename`, size() > 0 for empty(), and
  NOLINTs where a raw v8::TryCatch is reset right after its probe and
  where apiWrapperDeserializer's `{}` is needed because its default
  constructor is explicit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
failClosed() throws a JavaScript error. When the zygote's top level
was being terminated, by a startup CPU limit for instance, that throw
replaced the pending termination and let the top level run on. Return
without throwing while execution is terminating; the recorded use
still fails the zygote.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bakeSnapshot() in snapshot-test destroyed its WrappablesSerializeMetadata
after leaving the isolate lock. Its entries root cppgc shims through
cppgc::Persistent, which must be released by the thread holding the
isolate lock once a v8::Locker has been used; V8 builds with cppgc
DCHECKs abort with "IsCreationThread()". Declare it inside the lock, as
Worker::Worker does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The test asserted that the output mentions "fallback" anywhere, which
the service list alone satisfies. Check that the skip line is the one
for the `fallback` service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dcarney-cf and others added 19 commits November 11, 2026 06:54
A Worker started from a startup snapshot re-registered the zygote's
top-level listeners by calling the global's addEventListener with
{once}. That had three problems:

* It ran whatever the top level left in globalThis.addEventListener. A
  wrapper ran a second time, and a replacement that does nothing lost
  the listener. One that is not a function, or that throws, failed
  the Worker's startup outside any error handling, with no fallback.
* The passive option was dropped, so preventDefault() took effect in a
  listener registered as passive.
* Re-deriving the callback re-read an object listener's handleEvent,
  which the top level may have reassigned since it registered it.

The zygote now records what each registration derived (identity,
callback and receiver) together with once and passive. The restored
Worker rebuilds the callback through a type handler that
Worker::Api::tryGetEventListenerCallbackTypeHandler() supplies, and
inserts it with EventTarget::restoreSnapshotListener(). No JavaScript
runs, and the special-event warning is no longer printed a second time.
An Api without the type handler keeps a zygote that registered a
global listener from producing a snapshot.

startup-snapshot-listeners-test covers a passive listener, a replaced
addEventListener and a reassigned handleEvent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two gaps in the handling of the properties V8 adds to a context only
when restoring it from a snapshot:

* Deleting a FAIL_CLOSED property (`delete globalThis.WebAssembly`)
  does not call its getter, so the zygote succeeded, but V8 re-added
  the property on restore: the restored Worker had what the top level
  had removed. The deletion is now recorded alongside the
  Error.stackTraceLimit state, and the restored context deletes what V8
  added.
* Temporal and Date.prototype.toTemporalInstant were missing from
  RESTORE_TIME_GLOBALS. V8 installs them in
  InitializeGlobal_harmony_temporal(), which it skips in the zygote, and
  with JSObject::SetAccessor(), which replaces a property of the same
  name: a top-level polyfill was silently overwritten on restore, and
  then deleted by newContext() for a Worker without the temporal flag.
  In a context with Temporal the names are now FAIL_CLOSED. In one
  without it they stay absent, as in a normal context, and a top level
  that defines one fails the zygote. Date.prototype joins the holders
  that must stay extensible, read from a new v8::Date rather than a
  context data slot, since the embedder-data array has no slot to spare.

startup-snapshot-globals-test covers the deletion, a Temporal probe and
polyfill with and without the temporal flag, and a frozen
Date.prototype.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With nodejs_compat_v2 the `process` and `Buffer` globals are accessor
properties whose values live on the ServiceWorkerGlobalScope, not on
the global object, and a Worker started from a snapshot gets a fresh
one. A top-level `globalThis.process = ...` or `globalThis.Buffer = ...`
was therefore lost: the restored Worker resolved the module defaults
again.

The zygote now pins what its global scope holds for the two
(ServiceWorkerGlobalScope::getSnapshotState()) into
SnapshotArtifact::globalScopeStateIndex, and the restored global scope
takes it over (restoreSnapshotState()).

startup-snapshot-globals-test covers both assignments, and a top-level
process.env write. That one still falls back: evaluating node:process
reaches UrlUtil, a Rust JSG resource, and Rust resource types have no
snapshot transfer yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Top-level code commonly keeps a TextDecoder, which made the zygote
reject the snapshot. A decoder between inputs is its encoding and its
options, so the clone is a fresh decoder of the same kind (ICU or
legacy). A decoder that a streaming decode left with part of an input
pending is not transferred; TextDecoder now tracks whether its last
decode streamed. Decoder::getEncoding() becomes const so that the
const snapshotClone() can read it.

startup-snapshot-wrappables-test keeps a fatal UTF-8 decoder and a
windows-1252 one at top level, and checks that a mid-stream decoder
falls back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A restored JSG object is built afresh, by its type's constructor or a
snapshotClone(), so any jsg::Ref it holds points at a new object rather
than at the one behind the restored wrapper. For Crypto that broke
identity: a top-level `const subtle = crypto.subtle` was no longer
`crypto.subtle` at request time, because the restored Crypto
constructed its own SubtleCrypto.

Wrappable gains snapshotReferences(), which names the objects an
instance refers to in the zygote, and snapshotRelink(), which hands a
restored instance the restored instances of those once every wrapper is
linked. recordLiveWrappables() resolves the references to snapshot
slots (SnapshotArtifact::LiveWrappable::references), and
WrappableDeserializeMetadata::relinkReferences() runs right before the
slots are released. Object gets two helpers for the casts the private
Wrappable base needs. Crypto uses them for `subtle`.

startup-snapshot-wrappables-test checks the identity of crypto,
crypto.subtle and navigator across the snapshot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Without multiple pointer-compression cages every isolate shares the
default IsolateGroup's read-only heap. V8 builds it from the read-only
snapshot of whichever isolate the group starts with, and rebuilds it
when the group empties, as it does between a zygote's isolate and the
Worker's. A read-only snapshot taken by a zygote differs from the
built-in one only in its trailer, the zygote isolate's next
SharedFunctionInfo unique id, but:

* DEBUG builds CHECK that every isolate of a group sets the read-only
  heap up from a snapshot with the same checksum. A zygote created after
  a Worker restored from a custom snapshot rebuilt the heap therefore
  aborts, which is what failed the linux-arm debug job of every
  multi-Worker @all-autogates test.
* An isolate that joins an existing read-only heap takes its next id
  from the snapshot the heap came from. A Worker restored from a custom
  snapshot while built-in isolates hold the heap, the usual case in a
  busy process, hands out again the ids of the SharedFunctionInfos the
  zygote created; V8 keys debugger bookkeeping by them.

patches/v8/0053 writes the id as a fixed-width uint32, leaves it out of
the read-only heap's checksum, and has an isolate that joins an
existing read-only heap continue past its own snapshot's id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
setModuleFallbackCallback() is installed on the Worker's isolate only,
after the zygote has run. A zygote whose top level tolerates a failed
import, `try { await import(x) } catch {}` or a guarded require(),
therefore baked the failure in, and the Worker started from the
snapshot never consulted the fallback service. A Worker configured with
one now starts without a snapshot, which also makes the restore's
handling of a pinned module with no registry entry unconditional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A subclass of a stateless type inherits jsgSnapshotStateless, so a
startup snapshot would record it by tag and rebuild it as a fresh
instance, silently dropping the subclass's own state. The snapshotClone()
path already guards against the same mistake; the stateless one now
fails to compile instead. The stateless types that were not final are
made final; none has a subclass in workerd or edgeworker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
restoreConstructorTemplatesFromSnapshot() ran only when an Isolate
constructor instantiated the default type wrapper itself. An isolate
built with instantiateTypeWrapper = false and given its wrapper later
through instantiateDefaultWrapper() kept fresh templates, so every
wrapper restored from a snapshot would fail the receiver check of its
own type's methods. instantiateDefaultWrapper() now does the restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Describe the listener replay in C++, the restore-time globals' deletion
replay and Temporal handling, the process/Buffer state, references
between transferred objects, jsg::Function transfer, the module
fallback exclusion, the final requirement on stateless types and the
read-only heap patch, and list what the tests now cover.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
compileModules() calls tryTakeSnapshotModule() for every bundle ES
module, which cloned the module's path for a lookup in the seed table
even in a Worker that was not started from a snapshot, where the table
is always empty. Return right away then, so that a Worker the pipeline
does not touch does no extra work per module.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The zygote captured the intrinsics V8 adds restore-time properties to
(Error, Iterator, Iterator.prototype) in three new ContextDataSlots,
which raised the highest slot to 12 and required building V8 with
v8_embedder_data_array_size 13. An embedder whose V8 is built with the
default 10, as edgeworker's is, then failed to compile the static_assert
on ContextDataSlot::MAX_DATA_SLOT.

The zygote now holds the captured intrinsics as handles on IsolateBase,
tied to the context they came from, and
removeRestoreTimeGlobalsBeforeSnapshot() stores them in the record it
already pins into the snapshot, where replayRestoreTimeGlobalsAfterLoad()
finds them for the restored context. The handles are released once the
record is pinned, or with the isolate. The slots are removed and the V8
embedder data array is back to 10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
snapshot.h only forward-declares Wrappable, but defined
~SnapshotArtifact() inline, and destroying `liveWrappables` destroys the
kj::Own<Wrappable> a transfer can hold. A translation unit that includes
snapshot.h without the complete Wrappable failed to compile, as does
parsing the header on its own (edgeworker's build does). The destructor
is now defined in snapshot.c++.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A zygote whose top level leaves a generator, async function or async
generator suspended, for instance an async ReadableStream pull() that
awaits a promise a later request resolves, could not be restored
correctly. CreateBlob(kClear) discards the bytecode of every function
it can recompile, including one a suspended generator will resume in,
so the restored Worker resumed it in a lazily recompiled copy of that
bytecode. Debug builds with --debug-code abort there ("Missing bytecode
array from function", from ResumeGeneratorTrampoline), which failed
src/tests/streams/iocontext:iocontext-ts@all-autogates downstream.
V8's own bytecode flushing never discards a resumable function's
bytecode, for this reason.

Patch V8 (patches/v8/0054) to add
SnapshotCreator::HasSuspendedGenerators(), which looks for a suspended
generator among the objects CreateBlob() would serialize, and have
createSnapshotBlob() reject the snapshot when it finds one, just before
CreateBlob(). The Worker then starts without a snapshot.
CreateBlob(kKeep) is no alternative: it keeps compiled code that the
context snapshot cannot reference.

snapshot-test checks that a suspended async function and a generator
that has not started fail the zygote, and that a generator function and
a finished generator go through.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The macOS CI job's API AST dump (//src/workerd/tools:dump_api_ast)
segfaults in Apple clang 21 (Xcode 26.6) since the binding types gained
their snapshotClone() overrides; upstream clang 21 dumps the same file
without trouble. Defining the overrides in the .c++ files keeps their
bodies out of the headers the dump parses. What they do is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apple clang 21 (clang-2100.1.1.101) segfaults in -ast-dump=json when
it visits a requires-expression requirement whose substitution
failed: the dumper treats the stored substitution diagnostic as an
Expr. jsgRecreateForSnapshot() and kSnapshotRecreateByTag both use
`requires(Lock& lock) { U(lock); }`, which fails substitution for
types without a Lock& constructor, crashing the macOS dump_api_ast
action. Use the equivalent type traits instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apple clang 21 (clang-2100.1.1.101) segfaults in -ast-dump, which
the macOS dump_api_ast action uses, on an instantiated
requires-expression whose compound requirement failed substitution:
the dumper reads the substitution failure as an expression.
snapshotClone()'s inline `{ f.clone() } -> std::same_as<Impl>` check
fails for every function-pointer Impl. A named concept keeps the
requires-expression out of the instantiated body.

This also reverts the previous commit, which replaced different
requires-expressions that do not trigger the crash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
makeCloneable() refuses a class that inherits from a built-in V8
serializes itself, and built that list at bootstrap time with
`typeof SharedArrayBuffer`. The bootstrap runs in the startup-snapshot
zygote, where SharedArrayBuffer is a restore-time global that fails
closed when touched (V8 adds it only once the snapshot is restored),
so every zygote failed and no Worker was started from a snapshot.
Leaving it out of the list in the zygote would instead bake a list
without it into the snapshot.

Recognize SharedArrayBuffer.prototype by its own @@toStringTag, which
reads no global and is the same in the zygote and in a restored Worker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The test starts some 25 Workers, each through a zygote and then from
its snapshot. Under edgeworker's debug build, which runs workerd's
tests with a 15-second medium timeout, its @all-autogates variant takes
about 5 seconds and timed out twice on loaded runners.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dcarney-cf
dcarney-cf requested review from a team as code owners November 11, 2026 06:59
@dcarney-cf dcarney-cf closed this Nov 11, 2026
@dcarney-cf
dcarney-cf deleted the dcarney/7880-internal-build branch November 11, 2026 07:00
@dcarney-cf
dcarney-cf restored the dcarney/7880-internal-build branch November 11, 2026 07:01
@dcarney-cf dcarney-cf reopened this Nov 11, 2026

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💬 Approved with comments — One WARNING: commit 50b7a17's fix for the requires-expressions that crash Apple clang's JSON AST dump is not in the head tree, which puts the macOS dump_api_ast action at risk. It affects CI tooling only, not the shipped runtime.

Findings: 2 warnings (2 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8362.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Code Quality] `requires(Lock& lock) { U(lock); }` is still in `jsgRecreateForSnapshot()`, although commit 50b7a17b says it was replaced to stop the Apple clang AST-dump crash
- **File:** src/workerd/jsg/jsg.h:1446

### [Code Quality] `kSnapshotRecreateByTag`'s static_assert still uses the requires-expressions that commit 50b7a17b says crash Apple clang's AST dump
- **File:** src/workerd/jsg/type-wrapper.h:1000

📋 Code Quality: ⚠️ 2 warnings

The code is sound overall. Commit 50b7a17's fix for an Apple clang crash is missing from the head tree.

Recommendation: 📝 Minor Comments

  • [WARNING] requires(Lock& lock) { U(lock); } is still in jsgRecreateForSnapshot(), although commit 50b7a17 says it was replaced to stop the Apple clang AST-dump crash (src/workerd/jsg/jsg.h:1446)
  • [WARNING] kSnapshotRecreateByTag's static_assert still uses the requires-expressions that commit 50b7a17 says crash Apple clang's AST dump (src/workerd/jsg/type-wrapper.h:1000)
View full review

The requires-expressions from commit 50b7a17 are still present.

Commit 50b7a17 ("Avoid requires-expressions that crash Apple clang's JSON AST dump") names jsgRecreateForSnapshot() and kSnapshotRecreateByTag as the sites to change, and says they now "use the equivalent type traits instead". At the head commit, both still use requires(Lock& lock) { U(lock); }:

  • src/workerd/jsg/jsg.h:1446
  • src/workerd/jsg/type-wrapper.h:1000

Some stateless types are only default-constructible. For them this requirement fails substitution, and that is the case the commit says crashes the macOS dump_api_ast action. function.h moved the same kind of check into a named concept, and these two sites need the same change.

The binding clones, the bootstrap restore, the listener replay, the serialization.ts change, wrappable record and restore, worker-factory gating and actor-ID cloning showed no problems.


✅ All other checks passed

🔒 Security: ✅ LGTM

No security issues found.

  • Where the snapshot comes from: The zygote isolate produces the snapshot in the same process, so the artifact does not cross a trust boundary.
  • Restoring: Deserialization checks the payload size and the slot index, and it rejects duplicate links.
  • Which bindings are allowed: A closed switch decides which bindings can be transferred and excludes a binding unless the switch allows it. Crypto keys, memory cache, wrapped and loopback bindings keep a Worker off the snapshot path.
  • Zygote isolation: The zygote runs with the inspector disallowed.

📖 AGENTS.md: ✅ LGTM

No issues found in the AGENTS.md changes.


⚡ Performance: ✅ LGTM

No performance regressions found.

  • Zygote: The zygote work happens once per zygote and is bounded. The settle loop runs at most 8 rounds.
  • Restore: The restore work runs once per Worker start and grows linearly with the number of recorded wrappables.
  • Workers without a snapshot: A Worker that is not started from a snapshot returns early from the seed lookup, so it does no extra work.

📝 Documentation: ✅ LGTM

No documentation issues found.


Reviewed commit: 83b5d711

Comment thread src/workerd/jsg/jsg.h
// A subclass would inherit the flag and be rebuilt as a fresh instance, losing its own state.
static_assert(std::is_final_v<U>,
"a type that sets jsgSnapshotStateless must be final: a subclass inherits the flag");
if constexpr (requires(Lock& lock) { U(lock); }) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ WARNING · Code Quality

requires(Lock& lock) { U(lock); } is still in jsgRecreateForSnapshot(), although commit 50b7a17 says it was replaced to stop the Apple clang AST-dump crash

Commit 50b7a17 says this requires-expression was replaced with a type trait because Apple clang 21 segfaults in -ast-dump=json when substitution fails here. The expression is still at the head commit. Substitution fails for any default-constructible stateless type, so the macOS dump_api_ast action can crash again. std::is_constructible_v<U, Lock&> is equivalent and avoids the crash.

Suggested change
if constexpr (requires(Lock& lock) { U(lock); }) {
if constexpr (std::is_constructible_v<U, Lock&>) {

([&]<typename U>() {
if constexpr (U::JSG_KIND == JsgKind::RESOURCE && requires { U::jsgSnapshotStateless; }) {
if constexpr (U::jsgSnapshotStateless) {
static_assert(requires(Lock& lock) { U(lock); } || requires { U(); },

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ WARNING · Code Quality

kSnapshotRecreateByTag's static_assert still uses the requires-expressions that commit 50b7a17 says crash Apple clang's AST dump

This static_assert has the same requires(Lock& lock) { U(lock); } pattern that commit 50b7a17 says it replaced with type traits. Substitution fails for a type without a Lock& constructor, which is the case the commit says crashes Apple clang's -ast-dump=json. Use the equivalent type traits instead.

Suggested change
static_assert(requires(Lock& lock) { U(lock); } || requires { U(); },
static_assert(std::is_constructible_v<U, Lock&> || std::is_default_constructible_v<U>,

@dcarney-cf dcarney-cf closed this pull request by merging all changes into main in ad91104 Nov 11, 2026
@dcarney-cf
dcarney-cf deleted the dcarney/7880-internal-build branch November 11, 2026 10:20
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.

3 participants