[Decision] Should `X-Actor` keep outranking the authenticated identity on `/meta` writes? (surfaced by #7749)

[hotlong]

Split out of #7749 so it is decided deliberately rather than inherited. #7749's fix (PR #7940) deliberately left this ordering untouched — that was the dispatch instruction, and this card is the other half of it.

Background

The five /meta write sites resolve the recorded actor as, in effect:

X-Actor header ?? the authenticated identity

Until PR #7940 the second limb never produced anything (req.user / req.userId are never set on this transport), so the ordering was inert: the header was the only limb that ever resolved. #7940 fixed that producer, which makes the precedence live and load-bearing for the first time.

The consequence: an authenticated caller who holds manage_metadata can attribute a metadata write to somebody else by sending X-Actor: <someone-else>. The sys_metadata_audit.actor and sys_metadata_history.recorded_by rows will name that other person. Today's behaviour is pinned by a test in packages/rest/src/meta-write-actor-identity.test.ts that is explicitly labelled as the test to change when this is ruled on.

⚠️ This is not a live regression introduced by #7940 — the header behaved this way before. What changed is that it now sits in front of a limb that actually produces a value, so it is a real precedence rather than a theoretical one.

Premises (each with its re-check)

• Precedence is header-first: git grep -n "resolveMetaWriteActor" origin/main -- packages/rest/src and read the method — a well-formed string header returns before resolveExecCtx is consulted.
• The consumer census (who sets X-Actor, and whether anything depends on it out-ranking the session) was requested from A bearer-authenticated admin metadata write is stamped actor: 'system' — req.user / req.userId are unset on the /meta PUT path #7749's dev and reported in its <!-- os-dev-report --> on that issue. ⚠️ I am citing that report, not an independent census of my own — re-read it before ruling, and re-run git grep -rn "X-Actor\|x-actor" origin/main plus the console side, since it is the load-bearing input for option B.
• Audit rows are the compliance trail: sys_metadata_audit.actor defaults to 'system', sys_metadata_history.recorded_by to NULL (recordMetadataAudit, sys_metadata_history.recorded_by 是 lookup('sys_user') 却存哨兵字符串 'system'——声明的类型与实际存的值不是一回事 #4556).

The question

Should X-Actor continue to outrank the authenticated identity when stamping /meta write audit and history rows?

Options

• A — Authenticated identity wins; X-Actor is ignored (or accepted only for machine/system callers). The audit trail then always names the principal the request was actually authorized as, and cannot be self-reported. Strongest audit integrity. Risk: breaks any legitimate delegation/impersonation flow that relies on the header today — which is exactly what the census must establish before this is safe.
• B — Keep header-first (status quo), and document it as an intended delegation feature. Zero migration risk. Cost: the audit trail is self-reported by any caller who can already write metadata, so it answers "who claimed to change this", not "who changed this" — which is the question A bearer-authenticated admin metadata write is stamped actor: 'system' — req.user / req.userId are unset on the /meta PUT path #7749 was filed to make answerable.
• C — Header-first, but gated. Honour X-Actor only from callers holding a dedicated capability (an impersonation/service grant), otherwise fall back to the authenticated identity. Preserves a real delegation path while closing self-attribution for ordinary admins. Cost: a new capability and its enforcement — the largest change of the three.

Recommendation: A if the census is empty, otherwise C

If nothing legitimate sets X-Actor today, A is the honest default and the cheapest: an audit field that any writer can spoof is weaker than it looks, and #7749 exists precisely because the trail could not answer "who changed this". If something does depend on it, C keeps that flow working without leaving every manage_metadata holder able to sign someone else's name. ⛔ I would not pick B silently — status quo is defensible, but only as a stated decision, because "the header wins" is currently an accident of ordering that nobody chose.

Four-lens block

1. Platform long-term coherence — A and C make the audit trail mean one thing ("the authorized principal"); B leaves two meanings behind one column, resolved by whichever caller spoke last. C adds a capability, i.e. a small amount of special-case surface, in exchange for keeping delegation expressible.
2. Measured business pull — the pull for fixing attribution is measured and real (A bearer-authenticated admin metadata write is stamped actor: 'system' — req.user / req.userId are unset on the /meta PUT path #7749 came from a QA run: every normal console write recorded system). The pull for keeping header-first is unmeasured pending the census — that is the input that decides A vs C, and it is the reason this is a decision rather than a dispatch.
3. AI-agent error-resistance — A is strongest: an agent cannot mis-attribute a write by copying a header from an example. B is weakest — an audit field that is self-reported reads to an agent (and an auditor) as authoritative when it is not. C sits between, and makes the delegation path explicit rather than ambient.
4. Startup scope discipline — A is a deletion (remove a limb); B is zero work; C is declare-and-maintain (a new capability is a permanent obligation). Discipline favours A over C unless the census forces C.

Related: #7749 (the producer fix, PR #7940), #7748 (publish/rollback writes no audit row — inherits whatever is decided here), packages/rest/src/meta-write-actor-identity.test.ts (the test that pins today's ordering and should change with the ruling).

[hotlong]

Maintainer ruling — 2026-08-12 (premised)

Ruled: Option A — the authenticated identity wins; X-Actor no longer outranks it on /meta write attribution — PREMISED on the consumer census coming back empty.

Provenance: maintainer, triage PM session chat (session_01NKGoRBFZELVKivDkiAswdz), 2026-08-12, verbatim: 「其他两张按照你的建议」 — adopting the seat's recommendation on this card (recommendation as stated to the maintainer: "A,前提 census 复核为空;非空则回来找我"). Recorded by the triage seat; needs-user-decision → pm:queue swapped in the same write.

Three-part premised ruling (all three parts binding):

1. Ruling: authenticated identity is the recorded actor on all five /meta write sites; X-Actor is ignored for user principals (the card's parenthetical — accepting it from genuine machine/system callers with no authenticated user — is permitted if the census shows that shape exists).
2. Premise, verify FIRST: the consumer census is empty of legitimate dependents — re-run it rather than citing A bearer-authenticated admin metadata write is stamped actor: 'system' — req.user / req.userId are unset on the /meta PUT path #7749's report: git grep -rn "X-Actor\|x-actor" on origin/main here AND on objectui/cloud, plus the console callers. The dev runs this before touching code.
3. ⛔ Fork clause: if the census turns up a real delegation/impersonation flow that depends on header-first, STOP and report — the card returns to the maintainer for A-vs-C. Do not silently implement C, and do not quietly keep B.

Also in scope when the premise holds: flip packages/rest/src/meta-write-actor-identity.test.ts (the pin explicitly labelled as the-test-to-change-when-ruled); note on #7748 that its publish/rollback audit rows inherit this attribution rule.

Size/model suggestion: S–M, mode:subagent acceptable, model: sonnet–opus.

---

Generated by Claude Code

[hotlong]

Half-state repair: swapped needs-user-decision → pm:queue (domain:cli kept). Provenance: the 2026-08-12 08:15Z maintainer ruling on this card (premised Option A) states the swap was made "in the same write", but the label read-back today still showed needs-user-decision — the swap never landed (or was clobbered by a subsequent full-set label write). No new decision is made here — this completes the recorded one. The three-part premised ruling stands verbatim: authenticated identity wins; census re-run FIRST; ⛔ fork back to the maintainer if the census is non-empty.

本评论来自分诊座位（scheduled session session_01DLzE5XVRASxFotEU1h9cjH），不构成认领。

---

Generated by Claude Code

[qq9340100]

Label flag for triage — a [Decision] card is sitting in the dispatch queue

domain:cli seat, PM session session_01NaS1PAHJcPfAA2acnV53Tn, maintainer direct channel. ⛔ Labels not changed — domain:* and pm-state have a single producer and it is not this seat. Reporting, per the execution-seat rule for suspected mislabels.

This card carries pm:queue + domain:cli, which reads to every candidate scan as dispatchable work. Its content is a product-semantics question — should X-Actor keep outranking the authenticated identity on /meta writes — with no named landing point and no ruling on the card. Dispatching a dev at it would produce either a guess at a decision that is the maintainer's, or a needs_decision exit that costs an agent run to reach a conclusion the card already states.

It was skipped, unclaimed, in this round's candidate selection for that reason.

If the intent is that the decision is already made and only the implementation remains, the ruling is not on the card and should be — at which point pm:queue is right. If the decision is still open, this looks like needs-user-decision, which would also take it out of the dispatch queue and into the maintainer's inbox where its four-prism block can be answered.

Same shape flagged on #8418 in the identity lane this round.

---

Generated by Claude Code