A lowered hook body cannot name a record: no nameField accessor, no formula fields — so every message hand-composes the title, or falls back to the id

[os-zhuang]

Filed from objectstack-ai/hotcrm#1243 (PR objectstack-ai/hotcrm#1251) under the maintainer's standing rule that a platform capability gap found in the exemplar app is filed here rather than worked around there. Unassigned; this is an observation with a measurement, not a request for a specific API.

The gap

A hook body ships body-only: the CLI lowers handler to body.source and the runtime evaluates it in QuickJS with no module scope. Two consequences that meet here:

1. A hook cannot reach a formula field. ctx.previous / ctx.input carry stored columns; a formula like display_title is computed on read, so a body composing a message has to rebuild it.
2. There is no ctx helper that answers "what is this record called?" — no accessor for the object's nameField, and no way to resolve one for a related record either (a lookup column hands the body an id, and reading the name costs a findOne).

So the only way for a hook to name a record in a sentence is to re-implement the object's title inline, per hook.

Measured, in the exemplar app

objectstack-ai/hotcrm after PR #1251 has five inline reimplementations of a record title inside hook bodies:

hook	object	nameField	what the body re-composes inline
case_status_side_effects	crm_case	display_title (formula)	case_number + subject
lead_automation ×2	crm_lead	display_title (formula)	first_name + last_name + company
quote_workflow / quote_on_accepted	crm_quote	display_title (formula)	quote_number + name
contact_integrity ×2	crm_contact	full_name (formula)	first_name + last_name
opportunity_lifecycle	crm_opportunity	name (real column)	— the only one that is free

Each copy is a duplicate of a formula declared once in the object, and the copies can drift from it silently: nothing connects the display_title formula in quote.object.ts to the [quoteNumber, name].join(' - ') in quote.hook.ts. The app had to add a repo-local test (test/record-id-not-in-prose.test.ts) and a repo-local hygiene check to hold the invariant, both of which are compensating for the absence rather than expressing anything about CRM.

Why it produced a real defect, not just duplication

The cheap thing to write when there is no title accessor is the id — it is the one identifier a body always holds. hotcrm#1243 is that outcome measured end to end: eight sites across four hooks put a raw primary key into user-facing prose, and a walkthrough found 15 of 31 tasks in a demo org titled by a 16-character key, plus a duplicate-email refusal that answered "which contact already has this address?" with a string the UI never displays. #1208 had already fixed one instance of the same shape a month earlier.

The AI-authoring angle is the sharper half: an agent writing a hook reaches for ${record.id} precisely because it is the value in scope, and nothing in the platform makes the correct alternative closer to hand than the wrong one.

Not a proposal

Deliberately not naming an API shape — a title accessor on ctx, hydrating nameField into the pre-image, or making formula fields readable from a body are three different designs with different costs, and which (if any) is worth building is a scope call, not something one exemplar app's experience settles. Startup-scope discipline cuts against building any of them on one consumer's evidence; the counter-evidence is that this is the second card in the same class in the same app, and the workaround it forces is a duplicated formula per hook.

Recording the measurement so the decision is made on data rather than on the next occurrence.

[os-zhuang]

Triage: needs-user-decision + domain:engine (hook execution context / ctx helpers land in the runtime evaluation core), type Feature. This is a capability-appetite call — feature-class, manual floor — with a real measurement behind it (second card in the same class from the exemplar app; five inline title reimplementations; hotcrm#1243's id-in-prose defects). Options are the card's three designs: (a) a ctx title accessor, (b) hydrate nameField into the pre-image, (c) formula fields readable from hook bodies.

[facets-block]

• 实际业务需求:实测的真实缺陷,不是投机面——demo org 15/31 任务标题是 16 位主键,重复邮箱拒绝答非所问;每个写 hook 的应用都会撞。
• 项目长远合理性:对象上声明一次的 nameField/formula 是唯一权威;逐 hook 手抄拼接必然漂移,样板仓已被迫加两个补偿性检查——那是平台缺口的代偿,不是 CRM 的表达。
• 防 AI 写代码犯错:最锋利的一轴——agent 写 hook 时 ${record.id} 是手边唯一在握的值;平台不把正确答案放得比错误答案更近,这类缺陷会按 hook 数量线性再生。
• 创业阶段不扩散需求:三个设计里 (a) 最小(读侧 helper,不动存储与 formula 通用求值);(c) 是通用能力扩张,单一消费者证据撑不起。
  推荐:(a) 最小 ctx 标题访问器(可解析本记录与 lookup 关联记录的 nameField,formula 由服务端求值),(b)/(c) 不做。回「A」/「B」/「C」/「不做」即可。

---

Generated by Claude Code

[claude]

Maintainer ruling recorded (atomic four-part write)

Ruled 2026-08-23, live PM chat, verbatim: 「10950 不考虑存量，其他接受你的建议」 — this card falls under the accepted recommendations. Ruled: design (a) — a minimal ctx title accessor (resolves this record's and lookup-related records' nameField; formula evaluated server-side). Designs (b) pre-image hydration and (c) general formula readability are NOT approved. needs-user-decision → pm:queue in the same stroke (domain:engine, Feature).

---

Generated by Claude Code

[os-zhuang]

Engine seat — held one round, not neglected. Recording the wait on the card so it exists outside a session's memory.

The maintainer's ruling is on this card and I am not re-opening it: design (a), a minimal ctx title accessor; (b) and (c) not approved. This card is pm:queue and dispatchable.

Why it did not go out in the 17:10 batch: its landing site overlaps a card already in flight.

• A scalar data.id beside a NON-scalar where.id still silently drops the predicate — the remaining silent shape after the #11142 refusal, pinned by #5748 #11230 (dispatched 17:10) follows A scalar data.id beside a DIFFERENT scalar where.id silently drops the where.id predicate — the one unhonoured-predicate shape #11009's refusal deliberately left standing #11142's precedent, which landed in packages/metadata-core/src/engine-update-dispatch.ts, packages/objectql/src/engine.ts and packages/objectql/src/engine-update-dispatch.ts (squash 281069522).
• This card's fix lands on the runtime side of hook execution — packages/objectql/src/hook-wrappers.ts / engine.ts / packages/core — since the CLI half (lower-callables.ts, extract-hook-body.ts) only lowers handler to body.source; the ctx a body receives is assembled at runtime.

packages/objectql/src/engine.ts sits in both faces. Whether this card actually needs to touch it depends on how the accessor is threaded, and I have not measured that — which is exactly why it waits rather than going out on an assumption. This seat asserted a region from prose instead of a diff earlier today (#11201) and was wrong; the correction is on that card.

Exit condition, so this does not sit indefinitely: dispatch as soon as either holds — (1) #11230 lands, freeing engine.ts; or (2) the accessor's file face is measured and proves disjoint from it. Whichever comes first.

⚠️ One thing worth flagging for whoever implements it, because it shapes the work more than the ruling does: display_title is a formula in four of the five measured cases, and consequence 1 in the card body is that a hook cannot reach a formula field at all. So a nameField accessor that only reads stored columns would answer the wrong four of five. The ruling's parenthetical — "formula evaluated server-side" — is load-bearing, not decorative.

Triage's routing is confirmed correct, incidentally: the fix lands in the runtime evaluation core, not in the CLI that does the lowering.

---

Generated by Claude Code

[os-zhuang]

Claim — engine seat, session session_01RfyXxZ2WPjcjhuXpiQQc3y, branch claude/issue-11293-hook-ctx-title-accessor. pm:queue → pm:dispatched in one label write, read back.

⛔ First: the exit condition I wrote on this card was the WRONG criterion

At 17:52 I recorded: "dispatch as soon as either holds — (1) #11230 lands, freeing engine.ts…"

#11230 landed (PR #11432, squash 5d163792c) — and engine.ts was not freed. PR #11435 (another seat, "privileged driver-level reads join the ambient transaction") opened in the meantime and touches packages/objectql/src/engine.ts +58/−6.

The correct release criterion is the one this seat corrected itself on at 10:07 today and then failed to write into this card: "is there any open PR still occupying the file" — never "did my own PR merge". A file does not come out of the pit when your card lands; it comes out when nobody is standing in it. I wrote the wrong test down and then measured rather than trusting it, which is the only reason this was caught.

What the measurement actually says — dispatching anyway, on region

For another seat's PR the test is the region, not the whole file, and regions must be read from diff hunks rather than inferred from a title (the #11201 lesson, also today):

	region in engine.ts
#11435 (open, other seat)	hunks at 5937–5977, 5993–6004, 6062–6073, 6148–6162 — inside ObjectQL's transaction plumbing
this card's likely touch	nameField resolution at ~8093 (displayField: schema.nameField ?? schema.displayNameField), plus a comment at 1354
hook-wrappers.ts	not touched by #11435 at all — and this is where a hook body's ctx is assembled

~2000 lines apart, different methods, no shared symbol. Disjoint. The dispatch order names #11435's exact line ranges as off-limits and requires a stop-and-report if the fix turns out to need them.

The ruling, verbatim

「10950 不考虑存量，其他接受你的建议」

⇒ design (a): a minimal ctx title accessor resolving this record's and lookup-related records' nameField, with formula evaluated server-side. Designs (b) pre-image hydration and (c) general formula readability are NOT approved and are not to be built.

⚠️ Carried into the dispatch order as the thing that shapes the work more than the ruling does: four of the five measured cases have a display_title that is a formula, and the card's consequence 1 is that a hook body cannot reach a formula field at all. An accessor that only reads stored columns answers the wrong four of five. The ruling's parenthetical — formula evaluated server-side — is load-bearing.

Duplicate probe, both legs positive-controlled: no open PR claims this number, and git ls-remote origin 'refs/heads/*issue-11293*' is empty while the *issue-* pattern returns a live set.

---

Generated by Claude Code