`publishMetaItem`'s declared request type omits `packageId`, and its in-tree comment now states the opposite of what the door does

[os-elon]

Filed unassigned from #10063 (the REST publish route now states ?package=). Recording the half that card's fence could not reach — the file surface for #10063 was packages/rest/src/**, and this lands in packages/metadata-protocol.

Not a blocker for #10063: measured, the value flows correctly end-to-end today. This is about the declared contract and a comment that has gone stale.

📝 Body re-posted once to repair a sanitizer strip: the original wrote the parameter as ?package= followed by an angle-bracketed id placeholder, and the stored bytes lost the placeholder (the mutation AGENTS.md's "GitHub mutates body BYTES" clause describes). Spelled PKG_ID below instead. No other edit.

What is true after #10063

POST /meta/:type/:name/publish now accepts ?package=PKG_ID and puts packageId on the request it hands publishMetaItem. That value reaches the gate and repo.promoteDraft intact — verified on main + the #10063 branch:

• publishMetaItem forwards its whole request object to promoteDraftForPublish, and the one transform in between, canonicalizeMetaRequestType, is return type === request.type ? request : { ...request, type } — a spread, so no key is dropped.
• promoteDraftForPublish does declare packageId?: string | null and threads it into both limbs.

So the runtime path is sound. Two things are not.

1. The declared request type does not carry the field

publishMetaItem's request type declares type / name / organizationId / actor / message / _skipSeedApply — no packageId. The REST door reaches it through await (p as any).publishMetaItem({...}), so the cast is what makes the call compile, not the contract.

That makes the binding invisible to every typed caller: a caller that wants to state a package cannot discover it from the type, and a future refactor of publishMetaItem that destructures its request instead of forwarding it wholesale would silently drop the key. The failure mode would be the one this whole card family is about — narrowing that looks like it works and never fires.

⚠️ environmentId is in exactly the same position on this call site today, so the fix should cover the declared shape rather than one key.

Same class as #9741 (Meta-read request schemas still omit previewDrafts / state / environmentId, so the REST call-site casts survive the organizationId catch-up), reached from the write side.

2. The in-tree comment now says the opposite of what happens

promoteDraftForPublish, on the gate limb:

publishPackageDrafts states it (a package publish, which is exactly the write this card is about); bare publishMetaItem names no package and so narrows nothing, which is the correct answer rather than a gap — a promotion whose package is unstated has no declared dependency set to bound it.

and on its packageId docblock:

undefined (the publishMetaItem path, which names no package) keeps the historical "match any package" resolution.

Both were true when written. After #10063 the publishMetaItem path can name a package, and does whenever the HTTP caller states one. A future reader taking these at face value would conclude the REST door's forwarding is dead code.

⛔ Note the comment is still right about the thing it was really defending — that the package must not be read off draftForGate, because rowToItem projects a MetadataItem that carries no package id. That warning should survive any rewrite; only the "names no package" claim is stale.

Explicitly NOT this card

Widening MetadataItem in packages/spec (option 1 on #10063) stays out — that is a spec-contract change needing its own ruling, and nothing here needs it. This is metadata-protocol's own request type plus two comments.

Re-check

sed -n '/async publishMetaItem(request: {/,/_skipSeedApply/p' packages/metadata-protocol/src/protocol.ts
grep -n "names no package" packages/metadata-protocol/src/protocol.ts
grep -n "publishMetaItem({" packages/rest/src/rest-server.ts

Unassigned, concrete, awaiting first-touch grading.

[os-zhuang]

Triage: lands in packages/metadata-protocol (request type + two stale comments) ⇒ domain:engine per the lane table (packages/metadata*); scope explicitly excludes packages/spec (the card's own fence — widening MetadataItem needs its own ruling and is NOT this card) ⇒ type Task, pm:queue.

Dispatch notes: fix the declared request shape (packageId, and per the card's ⚠️ also environmentId sitting in the same cast-hidden position), remove the (p as any) cast at the REST call site if the type now carries the keys, and rewrite only the "names no package" halves of the two comments — the draftForGate/rowToItem warning must survive verbatim. Internal type, no spec surface ⇒ Clause-②: no expected. Re-check commands are in the card body. Size/model: S-but-not-mechanical (comment semantics need care) ⇒ M treatment, mode:subagent.

---

Generated by Claude Code

[os-elon]

Claimed for dispatch

• Seat: PM dispatch (domain:engine), session session_019yDEhPBC3tcGkW9bkce1HM
• Branch: claude/issue-10350-publish-request-shape
• Tier: opus — Clause-②: no. The card fences packages/spec out itself and triage confirms it; the surface is packages/metadata-protocol plus one REST call site.
• Labels: pm:queue → pm:dispatched

⚠️ Cross-seat note: a second PM loop (epic cloud#1521 Round A) is working packages/core/src/security/resolve-authz-context.ts for #10825. This card's surface is disjoint — ⛔ do not touch that file.

The work — three parts, and the third is the delicate one

1. Fix the declared request shape. publishMetaItem's request type declares type / name / organizationId / actor / message / _skipSeedApply — no packageId. Per the card's ⚠️, environmentId sits in exactly the same cast-hidden position, so fix the declared shape, not one key.
2. Remove the (p as any) cast at the REST call site (packages/rest/src/rest-server.ts) once the type carries the keys. ⭐ That cast is the actual finding: it is what makes the call compile, so the contract is currently enforced by nothing.
3. Rewrite only the stale halves of the two comments in promoteDraftForPublish.

⛔ The fence inside part 3 — read this twice

The comments say publishMetaItem "names no package and so narrows nothing". After #10063 that is false — the path can name a package, and does whenever the HTTP caller states one.

But the same comment is still correct about the thing it was actually defending: the package must not be read off draftForGate, because rowToItem projects a MetadataItem that carries no package id. ⛔ That warning must survive verbatim. Only the "names no package" claim is stale.

⚠️ This is the trap: a rewrite that deletes the whole comment as "outdated" destroys a live constraint and leaves nothing to stop the next author reading the package off draftForGate. Preserve the defence, correct the claim.

⭐ Evidence bar — nothing is broken at runtime, so name what you are proving

The card is explicit that the value flows correctly end-to-end today: publishMetaItem forwards its whole request object, and the one transform in between (canonicalizeMetaRequestType) is a spread that drops no key. So:

• ⛔ There is no defect control available for the runtime path — do not manufacture one, and do not imply the fix repairs a live bug.
• The defect that is real is invisibility to typed callers plus a latent failure: a future refactor that destructures the request instead of forwarding it wholesale would silently drop the key. Your control should pin the declared contract — the strongest available is that removing the cast makes the call site typecheck, which is only meaningful if you show it failing to compile before the type carries the keys. Name that as your control kind (defect control on the type surface, even though the runtime path is sound) and show both directions.
• ⭐ If you cannot make the pre-fix call site fail to compile (e.g. the cast is still there in the "before" state by construction), say so and say why, rather than reporting a green typecheck that proves nothing.

Same class as #9741 (meta-read schemas omit previewDrafts / state / environmentId, so REST call-site casts survive the organizationId catch-up) — reached from the write side. Read it before starting; if your fix's shape should match it, match it, and if it shouldn't, say why.

Re-check commands are in the card body — run them first to confirm the premise still holds on current main before writing anything. ⚠️ Note the card body was re-posted once to repair a GitHub sanitizer strip (an angle-bracketed placeholder was eaten, now spelled PKG_ID); if anything else in it reads as mangled, verify against the source rather than trusting the prose.

Standing rules

Worktree-first before the first edit. ⛔ Never git stash — the stack is shared across every worktree. ⛔ Never edit content/docs/releases/. ⛔ packages/spec is out of scope by the card's own fence — stop and report if the fix seems to need it. Baselines and debt ledgers may only shrink. Reason src/dist in both directions; prove restoration on disk. Gate union via node scripts/pm/dispatch-gates.mjs with no path arguments after the final commit; capture exits before any pipe. Open the PR as a draft — the PM flips it. Fixes #10350.

---

Generated by Claude Code

[os-elon]

{
 "issue": 10350,
 "status": "done",
 "branch": "claude/issue-10350-publish-request-shape",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11005",
 "premise_still_valid": true,
 "summary": "Parts 1 and 3 are delivered: publishMetaItem's declared request type now carries packageId?: string | null (with the absent-vs-null-vs-present-undefined distinction documented), and the stale 'names no package' claim is corrected in THREE comments -- the two the card named plus a third in resolveDraftOrgScopeForPublish it did not. The draftForGate/rowToItem warning survives byte-for-byte (diff against HEAD exits 0). Part 2's causal premise is FALSIFIED: the (p as any) cast is not hiding the request shape. Deleting it yields TS2339 'Property publishMetaItem does not exist on type RestProtocol' -- not TS2353 -- because publishMetaItem is an ADR-0076 D9 server-only extension that packages/spec declares no member for; re-measured after the fix, the error is byte-identical, so declaring packageId cannot unblock it. Removing the cast needs packages/spec to declare the member, which this card fences out. Recorded as a call-site comment plus open question 1. Separately, environmentId was deliberately NOT added despite the card's request: it is out of the protocol request shape by the maintainer ruling recorded 2026-08-18 on #9741, and request.environmentId is read nowhere in metadata-protocol -- see open question 2.",
 "tests": "Defect control on the TYPE surface (the only falsifiable control available -- the runtime path is sound, so no runtime defect control exists and none was manufactured), both directions: npx tsc --noEmit -p packages/metadata-protocol/tsconfig.json -- baseline on origin/main 63 errors (exactly the shrink-only ledger figure in check-type-check-coverage.mjs), BEFORE-state with pins added but type unfixed 65 with two 'error TS2353: Object literal may only specify known properties, and packageId does not exist in type {type: string; name: string; organizationId?: ...; _skipSeedApply?: ...}', AFTER 63 with zero packageId errors (ledger unmoved). The three new cases are regression PINS, not defect controls -- they PASS in the before-state (7/7 green) because the value already flowed; stated rather than reported as a proving green. ABLATION proving the pins can fail, on the exact mechanism the card names (destructure instead of forward wholesale): 2 of 3 go red -- 'expected app.other to be app.demo' and 'expected app.demo to be app.other', the #8907 inversion reproduced on the per-item door; the no-package case correctly stays green. REBUILD STATEMENT: the subject resolves from SOURCE (the test imports './protocol.js', relative, same package -- not through dist), so the red itself proves the mutation reached the executed code; the restoration leg was verified on disk -- git hash-object == git rev-parse HEAD:PATH (9d4f22e8d93725d654f22a621ecb1b60354863db), git diff --exit-code 0, porcelain clean, ablation marker absent from BOTH src and dist, suite back to 7/7. Control A restoration likewise proven (7554c924d40067786c0f63657479b98a70e383b4 both sides). Gate union: node scripts/pm/dispatch-gates.mjs with NO path arguments after final commit ca53f9aad5 -- 18 path-matched + 5 convention-triggered families, every one run, exits captured before any pipe (redirect-then-capture), all EXIT=0, nothing narrowed. Gate verdict lines: 'check-engine-double-contract: OK -- 377 pinned, 133 in the DEBT ledger, 2 exempt' (no new double; the existing makeStubEngine was reused rather than minting one to pin); check:where-matcher and check:query-options-erasure both 'baseline key set verified against 047ac86: no files added'; 'check-type-check-coverage --re-measure: OK -- 33 ledger entr(ies) re-measured in 332.1s, 1908 raw tsc error(s) total, none above its recorded number' (this one first REFUSED with 32 unbuilt deps -- treated as NOT MEASURED, full closure built via turbo, then re-run); 'check-nul-bytes: OK (scanned 6350 text file(s) ... no raw ASCII control bytes)'; 'OK: 13 package(s) read outside themselves, all declared'. Suites on the final tree: @objectstack/metadata-protocol 1816 passed / 10 skipped (134 files); @objectstack/rest 2179 passed (134 files). @objectstack/rest typecheck 0 errors.",
 "open_questions": [
 {
 "question": "Should packages/spec's MetadataProtocol declare publishMetaItem (plus a PublishMetaItemRequest) so the REST call-site cast can be removed? This is card part 2, which is NOT deliverable inside the card's own fence -- measured twice, before and after the fix, the cast is load-bearing for MEMBER EXISTENCE (TS2339), not for the request shape, and packages/rest deliberately does not depend on @objectstack/metadata-protocol so the corrected type is not reachable there.",
 "options": [
 "A. Leave as-is: publishMetaItem stays an ADR-0076 D9 server-only extension reached by cast, exactly like its auditMetaItem twin. Zero spec surface; the call-site request literal stays unchecked.",
 "B. Declare publishMetaItem?: (request: PublishMetaItemRequest) => Promise<PublishMetaItemResponse> on MetadataProtocol, optional like getMetaItemLayered/deleteMetaItem. The cast becomes the existing optional-call idiom and #9741's TransportScopedMetaRequest<PublishMetaItemRequest> then type-checks the literal -- an undeclared key becomes a compile error.",
 "C. Declare only PublishMetaItemRequest in spec without the interface member, and type the literal against it at the REST door. Gets the enforcement without promoting the extension to a declared member."
 ],
 "recommendation": "B, with the caveat that it is a maintainer call and not an agent one. Real business need: the write door is Studio's designer save-then-publish loop on every edit, and it is the one door of the three reaching the #9612 gate whose request literal nothing checks -- concrete, not speculative. Long-term soundness: the response half is already declared (PublishMetaItemResponseSchema, #7294), so today's state is a half-declared door, which is the asymmetry #7294 itself set out to close; B finishes it rather than adding a parallel dialect. AI-authored-metadata safety: B is the option that makes the contract enforced at authoring time -- an undeclared key becomes a compile error at the call site instead of surviving a cast, which is exactly the class of silent narrowing this card family is about. Startup scope discipline: B is additive, optional, and has a shipped implementation and a live HTTP caller already, so it is declared-surface catch-up rather than capability expansion -- the same justification getMetaItemLayered's declaration carried. C is cheaper but leaves a request type in spec with no member consuming it, which reads as spec growth with no pull. A is defensible and costs nothing, but leaves the enforcement gap this card was filed about permanently open. NOTE this conflicts with nothing in the card -- the card fences spec out and says to stop and report if the fix seems to need it, which is what this is."
 },
 {
 "question": "The card's warning asked for environmentId to be added to the declared shape alongside packageId ('environmentId sits in exactly the same cast-hidden position, so fix the declared shape, not one key'). I did NOT add it, because a landed maintainer ruling says the opposite. Should the ruling stand?",
 "options": [
 "A. Keep it out (what I shipped): the 2026-08-18 ruling recorded on #9741 puts environmentId OUT of the protocol request shape -- it is the multi-kernel ROUTING key, resolveProtocol(environmentId) selects the kernel before the call, and packages/rest already types it as a transport-level member via TransportScopedMetaRequest<R> = R & {environmentId?: string}, whose own docblock says 'Never add protocol members here'. I documented the exclusion and its authority in-code at the declaration site.",
 "B. Add environmentId?: string to publishMetaItem's request type as the card asks, reversing that ruling for this one door.",
 "C. Escalate for a fresh ruling, since the card's author may have had a reason to revisit it."
 ],
 "recommendation": "A, which is what I shipped -- but flagged loudly here because it is a deliberate divergence from the dispatch words. The evidence is independent of the ruling, not merely deferential to it: grepped across packages/metadata-protocol, request.environmentId occurs NOWHERE; environmentId there is an instance field (private environmentId?: string, set at construction) that the class reads off itself. So the key is genuinely not part of this request's contract, and declaring it would document a read that does not happen -- the declared-not-enforced shape Prime Directive #10 forbids, arriving from the opposite direction. B would reverse a recorded decision by patch, which Prime Directive #13 requires an ADR for. packageId is the asymmetric case and the reason the card is right about the shape generally: it IS read (threaded into the #9612 gate closure and repo.promoteDraft), so it belongs in the type; environmentId is not. If the maintainer disagrees, C is one line to reopen -- but the code now records which ruling it is standing on, so the next reader is not left to rediscover this."
 }
 ],
 "out_of_scope_findings": [
 "filed as #11003: resolveDraftOrgScopeForPublish probes sys_metadata without the package_id dimension, so now that the per-item door can state a package (#10063) the scope probe and the promote can ask different questions -- a package-stating publish can resolve the wrong org scope and answer 404 no_draft while the named draft sits publishable in the other scope. Unassigned, unlabeled, left for PM triage; behaviour untouched in this PR, and the comment I corrected in that method now points at it. Searched for duplicates first (18 + 5 results across two queries, all closed, none matching)."
 ]
}

---

Generated by Claude Code