Skip to content

Add ephemeral CHASM component fields - #13085

Merged
bergundy merged 5 commits into
temporalio:mainfrom
bergundy:chasm-ephemeral-components
Nov 18, 2026
Merged

bergundy merged 5 commits into
temporalio:mainfrom
bergundy:chasm-ephemeral-components

Conversation

@bergundy

@bergundy bergundy commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

What changed?

Added chasm.ComponentFieldEphemeral(), a component field option that marks a component, and everything under it, as in-memory only.

  • Ephemeral nodes are never serialized, persisted, snapshotted, or replicated. They only live while the execution's mutable state is loaded, and they're lost when it's reloaded.
  • A map that was never persisted isn't persisted while it only holds ephemeral items. Adding an ephemeral item to an empty map doesn't persist the map, and removing the item leaves no tombstone. The map is persisted once it holds a durable item.
  • Pending component metadata, e.g. request links, isn't applied to ephemeral nodes.
  • Adding tasks to an ephemeral component, including immediate pure tasks, returns an internal error (via softassert) instead of silently dropping the tasks.
  • Replacing a field's value deletes the replaced node's subtree. Paths the new node writes are rewritten rather than deleted. This also fixes durable replacements, where descendants the new value didn't have were left behind and came back on reload.
  • A durable data pointer to data inside an ephemeral subtree fails the transaction, since it would dangle after a reload.
  • A replicated node at or under an ephemeral node replaces the ephemeral node and its subtree.

Why?

This is the first step towards direct Nexus calls (temporalio/api#720). A caller outside of a workflow attaches an ephemeral completion callback to the execution it waits on, turning its request into a long poll. The callback is a regular CHASM Callback component, but it belongs to an in-flight request, so it must never be persisted.

A follow-up PR will skip persisting update transactions that make no durable changes, so that attaching an ephemeral component doesn't cost a write.

How did you test it?

  • built
  • run locally and tested manually
  • covered by existing tests
  • added new unit test(s)
  • added new functional test(s)

New chasm/tree_test.go tests cover:

  • An ephemeral item and its subtree are excluded from mutations and snapshots, including when the item is mutated or has request links set.
  • The ephemeral item keeps its in-memory state across transactions.
  • A map that only held ephemeral items is persisted once a durable item is added.
  • Removing the ephemeral item leaves no tombstone, while removing the durable item does.
  • Emptying a never-persisted map removes it without a tombstone.
  • Adding tasks to an ephemeral component is rejected.
  • Replacing a durable item with an ephemeral one deletes the durable item and its subtree.
  • Replacing a durable component with a durable one deletes only the descendants the new component doesn't have.
  • A replicated durable item replaces an ephemeral item at the same path, while other ephemeral items keep their in-memory state.
  • A durable data pointer to ephemeral data is rejected, while pointers within the ephemeral subtree are allowed.

Potential risks

  • Components that use ephemeral fields must treat them as a cache. Their state disappears when the mutable state is reloaded, evicted, or moved to another shard.
  • syncSubComponents now always serializes a collection that was never persisted. Without ephemeral fields, that's only a newly created collection, which was already serialized before this change.

ComponentFieldEphemeral marks a component and its subtree as in-memory only. Ephemeral nodes
are never serialized, persisted, snapshotted or replicated, and adding tasks to them is an
error. A collection that was never persisted and only holds ephemeral items is ephemeral too,
and is persisted once it holds a durable item.
@bergundy
bergundy marked this pull request as ready for review November 13, 2026 22:47
@bergundy
bergundy requested a review from a team as a code owner November 13, 2026 22:47
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Claude encountered an error after 0s —— View job


I'll analyze this and get back to you.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @bergundy's task in 1m 56s —— View job


Reviewed 5 files, 2 findings.

Comment thread chasm/tree.go

// Field is not empty but tree node is not set. It means this is a new field, and a node must be created.
childNode := newNode(n.nodeBase, n, fieldN)
childNode.ephemeral = internal.ephemeral || n.ephemeral

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Replacing a persisted item with an ephemeral one leaves the old row in the DB. syncSubField overwrites n.children[fieldN] with the new node and never deletes the old one. That's harmless for durable replacements because the new node re-writes the same path. An ephemeral node is skipped in closeTransactionSerializeNodes, though, so neither UpdatedNodes nor DeletedNodes gets the path, and the old durable component comes back on reload.

I reproduced this. Persist SubComponents["k"] as durable, then in the next transaction set SubComponents["k"] = NewComponentField(ctx, ..., ComponentFieldEphemeral()). The resulting mutation has UpdatedNodes=[] and DeletedNodes=map[].

Possible fix: when an existing child at fieldN is replaced by an ephemeral node, call delete(false) on the old child first so the tombstone is recorded. Alternatively, reject the replacement. It's worth a test either way.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed in 9b08ddd. When an ephemeral node replaces an existing child, syncSubField now deletes the old child first, so it and its subtree get tombstones. This only applies to ephemeral replacements: a durable replacement rewrites the same path, and persistence applies upserts before deletes, so tombstoning that path in the same mutation would drop the new copy.

Covered by TestCloseTransaction_EphemeralComponent_ReplacesDurable, which asserts DeletedNodes is exactly SubComponents/k and SubComponents/k/SubComponent11 after the replacement.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Correction to my reply above: the fix now covers every replacement, not just ephemeral ones (c010b27). I was wrong that tombstoning a path the new node rewrites would drop the new copy. closeTransactionSerializeNodes already removes a path from DeletedNodes when it writes the node. So only the old paths the new node doesn't have end up deleted.

That also fixes a bug in durable replacements that existed before this PR: descendants of the replaced node that the new value doesn't have were never deleted, so they came back on reload. Covered by TestCloseTransaction_ReplacedComponentDeletesSubtree.

Comment thread chasm/component_field_option.go Outdated

// ComponentFieldEphemeral marks the component, and everything under it, as ephemeral. Ephemeral components only live
// in memory, for as long as the execution's mutable state is loaded. They are never persisted or replicated, and they
// can't have tasks.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit, design: nothing stops a durable node from holding a pointer (ComponentPointerTo / deferred pointer) to an ephemeral component, or to something under one. The pointer node gets persisted, but its target won't exist after a reload, so the pointer dangles. Consider documenting this restriction here, or adding a softassert to serializePointerNode when the resolved target isEphemeral().

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed in 9b08ddd. Component pointers can't dangle here: they must target an ancestor, and ephemeral is inherited by descendants, so the pointer is ephemeral whenever its target is. Data pointers have no ancestor rule, so resolveDeferredPointers now fails the transaction when a durable data pointer targets ephemeral data. I put the check there rather than in serializePointerNode, since that's where pointer targets are already looked up and validated. I also documented the restriction on ComponentFieldEphemeral.

Covered by TestCloseTransaction_EphemeralComponent_RejectsDurableDataPointer, which also checks that pointers within the ephemeral subtree are still allowed.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Follow-up in cc1fe95. My reply above relies on everything under an ephemeral node being ephemeral, and that rule had a gap: nodes created by replication (applyUpdates) didn't inherit the flag. A replicated node at or under an ephemeral node, which needs a path collision after a failover while the mutable state stayed loaded, ended up durable under it or merged into it. applyUpdates now deletes the ephemeral subtree first, so the replicated node replaces it. Covered by TestApplyMutation_ReplacesEphemeralNode.

isEphemeral() is gone as well. Ephemeral now only means the node's flag, which every descendant inherits. The rule that a map that was never persisted isn't written while it only holds ephemeral items moved to a separate shouldPersist(), so that map no longer counts as an ephemeral node that later gets durable children.

Replacing a persisted node with an ephemeral one now deletes the old node, since the ephemeral
node doesn't overwrite its persisted copy. A durable data pointer to ephemeral data fails the
transaction, as it would dangle once the mutable state is reloaded.
A new durable node rewrites its own path but not necessarily the replaced node's whole subtree,
so descendants it doesn't have came back on reload. Delete the replaced subtree on any
replacement. Paths the new node writes are removed from DeletedNodes when it's serialized.
@awln-temporal
awln-temporal self-requested a review November 17, 2026 22:25
Ephemeral now only refers to the node flag, which all descendants inherit. The rule that a
never-persisted map holding only ephemeral items isn't persisted moves to shouldPersist, so
the map is no longer an ephemeral node that later gets durable children.

Replicated nodes didn't inherit the flag, so a node replicated at or under an ephemeral node
ended up durable under it, or merged into it. applyUpdates now deletes the ephemeral subtree
first, so the replicated node replaces it.
Comment thread chasm/tree.go
// The field's value was replaced. The new node may not overwrite the replaced node's whole subtree, or any
// of it if the new node is ephemeral, so delete the subtree. Paths that the new node writes are removed
// from DeletedNodes when it's serialized.
if err = oldChildNode.delete(false); err != nil {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

very nit: what about the behavior if someone does tc.SubComponent1 = NewComponentField(ctx, tc.SubComponent1.Get(ctx))? Seems like this deletes the child nodes, essentially resetting the component. I don't expect anyone to do this, but just wanted to highlight some hidden behavior.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Good catch. It kept the component's own data, but it deleted everything under it and left its sub-fields pointing at the deleted nodes. Before this PR the subtree wasn't deleted, but the in-memory tree lost track of it, so it diverged from what was persisted instead.

Fixed in aef1bd5: re-wrapping or moving an attached component, wrapping one component in two fields, and copying an attached field to another path now fail the transaction with an internal error instead of silently losing data.

A component's subtree and metadata belong to its node, so wrapping an attached component in a
new field, whether at the same path or another one, dropped its descendants and left its
sub-fields pointing at deleted nodes. Wrapping the same new component in two fields made the
fields share one value with separate nodes. Both now fail the transaction.

A field copied from another field holds a node at the other path, so it was never persisted at
its own path. This includes fields carried over into a component that replaces their parent,
whose nodes were deleted along with the replaced subtree. These fail the transaction too.

TestPointerAttributes attached sc1 to two fields, so its interface field gets its own component.
@bergundy
bergundy enabled auto-merge (squash) November 18, 2026 00:25
@bergundy
bergundy merged commit 506d381 into temporalio:main Nov 18, 2026
55 checks passed
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.

2 participants