The engine's reference-cleanup marker IS reachable from a hook on 17.0.0 GA — #720's "no marker reaches a hook" note is falsified, and three copies of a shape predicate rest on it #1165

Observation, not a defect: nothing is broken today. Filed because a load-bearing note in test/freeze-guard-reference-cleanup.test.ts is measurably wrong on the version we now ship, and three hook predicates were shaped by it.

Found while implementing #1072. Platform: @objectstack/* 17.0.0 GA (the note was written against 17.0.0-rc.6).

The note

test/freeze-guard-reference-cleanup.test.ts explains why the three freeze guards sniff the write SHAPE rather than reading a first-class marker:

A marker DOES exist, and it is deliberately out of reach: the engine tags its own cleanup write with __referentialFieldClear: true on the internal operation context (ObjectQL.cascadeDeleteRelations), but buildSession copies a fixed allow-list of keys into ctx.session and the __-prefixed operation-private keys are not among them (...). Preferring a first-class marker over shape-sniffing was the instruction; the marker is not offered to hooks, so the WRITE SHAPE is the only evidence there is. If a future platform release surfaces one, the drift pin at the bottom of this file is where to start, and switching to it is strictly better.

Measured

The ctx.session half of that is still true. The conclusion drawn from it is not: the marker reaches a hook by another route. Instrumenting a beforeUpdate on crm_lead and walking the context:

CASCADE  ctxKeys = [api, dispatch, event, input, object, previous, provenance, ql, session, transaction, user]
CASCADE  api keys = [engine, executionContext, joinedHandles]
CASCADE  MARKER  ctx.api.executionContext.__referentialFieldClear = true

HAND     ctxKeys = (identical)
HAND     api keys = [engine, executionContext, joinedHandles]
HAND     (no __referentialFieldClear anywhere)

Present on the engine's cleanup write, absent on a user's hand-clear of the same lookup — which is exactly the discrimination the three shape predicates were written to approximate, and cannot make: measured on GA, the two writes are otherwise byte-identical (same input, same ctx.user, same ctx.session), and the referenced record is still readable from both, so neither shape nor existence carries the answer.

Why this is filed rather than acted on

Reading it would be a worse fix than the shape predicate it replaces, for two reasons that are worth writing down before anyone finds the key and reaches for it:

1. It is an operation-private key. The __ prefix is a platform convention meaning "not part of the contract", the same convention buildSession enforces when it strips these from ctx.session. Building app correctness on it is an undeclared dependency that can vanish in a patch release without anyone calling it a break.
2. Reachability through the shipped path is unproven. Hook bodies run body-only inside QuickJS, and ctx.api there is not the object the handler was written against — buildSandboxApi returns engineCtx.api when it exposes object(), and otherwise builds a shim carrying no executionContext at all. A predicate that reads the marker could be green in the kernel test rig and silently false in production, which is the worst available outcome for a guard.

What would actually resolve it

A first-class, declared marker on the hook context — e.g. ctx.referentialFieldClear, declared on HookContextSchema in packages/spec and populated on every cleanup write. That is a platform ask, not an app change. With it, the three verbatim copies of the shape predicate (lead_automation, opportunity_lifecycle, quote_workflow) collapse into one honest read, the narrowness caveats in #720 stop being load-bearing, and the REFERENCE_FIELDS-completeness pin becomes unnecessary.

Until then the two concrete steps in this repo are:

• correct the note quoted above, which currently asserts something false about GA and would stop a reader from even looking;
• keep the shape predicate, and say in the note that the marker exists, where it is, and why it is deliberately not read.

Refs #720, #1072.

Generated by Claude Code