Repository navigation
client SDK: environments.update JSDoc promises plan/status/visibility writes the control plane rejects (400 since cloud#2193) #17825
Description
Problem
environments.update's JSDoc in the client SDK says a caller may change plan and status. Neither has ever taken effect: the control plane declares both columns read-only, so the values were silently dropped. Since cloud#2193 the route answers 400 for them instead of dropping them, so the doc now describes a call that fails.
The same doc comment also implies visibility is writable. The control plane forces visibility to private at create time and rejects the column on update. A maintainer ruling on 2026-09-12 keeps it that way until the public-listing feature exists, at which point it gets its own endpoint rather than the generic update.
Proposal
Correct the doc comment on the next SDK touch:
plan— not updatable through this call; plan changes go through the billing routes.status— not updatable through this call; use the lifecycle actions (archive / restore / suspend / resume).visibility— server-owned,privatetoday; a write entry will arrive with the public-listing feature.- State plainly that unknown or read-only keys are answered with 400, so callers do not assume a silent drop.
Acceptance
- The doc comment lists only fields the control plane actually accepts.
- If the SDK has a type for the update payload, read-only fields are not part of it (or are marked as such), so the compiler catches the mistake the comment used to invite.
Activity
os-sales commentedon Sep 13, 2026
Clause-②: no
check-clause2-carriers.mjs --pair 17948(exit 4). A separate correction comment was not enough: the checker re-read it and answered that the key was on the thread but not in the claim comment. ⛔ Nothing else below is changed.Claim: session
session_01TSf4DV7ziu4V5j73e46b7c·domain:cliexecution seat (#6024), R73 · 2026-09-13T06:46ZBranch:
claude/issue-17825-environments-update-jsdoc· worktree:/home/user/objectstack-issue-17825Declared file face (for the targeted in-flight check, and for anyone claiming near it):
⛔ Not in this face:
packages/rest/**,packages/spec/**, any route implementation. This card moves prose only — see the order's fence section.In-flight check, taken now: 19 open PRs read; 0 touch
packages/client/src/index.ts.origin/main84e6b05b6, 2026-09-13T06:45Z::2746:2775updateJSDoc:2907:2936updatesignature (patch: Record<string, unknown>):2938updateVisibility:3023:3058Control: 61
environmentsmentions in that file, so the readings are from a live instrument. ⛔ Do not search for triage's numbers.Dispatch order follows in the next comment.
domain:cliexecution PM seat · #6024 · R73Generated by Claude Code
os-sales commentedon Sep 13, 2026
Dispatch order — #17825 (
domain:cli, R73, dispatched 2026-09-13T06:48Z)Seat:
domain:cliexecution PM (#6024), sessionsession_01TSf4DV7ziu4V5j73e46b7c. Base ref for every reading below:origin/main84e6b05b6, read 2026-09-13T06:45Z.1. The ruling — quoted, ⛔ not paraphrased
Triage (#6015, comment
5651239400) split this card into a rulable half and a maintainer-floor half. Its words, verbatim:And the reason the surface is bigger than the card says:
⇒ This card moves prose only. ⛔ No signature, no type narrowing, no deprecation, no thrown error.
2. Current line numbers — every one in the triage grading has drifted
⛔ Do not search for triage's numbers. Re-derive your own before editing.
3. Every work item below is a premise you FALSIFY FIRST
:2775and:2936both still nameplanandstatusas updatable.update's payload isRecord<string, unknown>— i.e. there is no type to narrow, so the card's acceptance item 2 has no first half on this tree.updateVisibilityat:3058PATCHes the same generic route with{ visibility }.:2626'svisibility flipbelongs topublishDrafts— a different subject, ⛔ out of scope (expect drift on that number too).updateHostname(triage read:3014) goes through a/hostnamesub-route — ⛔ also out of scope.4. Acceptance
plan→ billing routes;status→ lifecycle actions (archive / restore / suspend / resume);visibility→ server-owned,privatetoday, its own endpoint arrives with public listing; and unknown or read-only keys are answered with 400, ⛔ not silently dropped — that last one is the card's most valuable sentence, because silent-drop is what a caller reasonably assumes today.updateVisibility's JSDoc: that the call is rejected today, and the 2026-09-12 maintainer ruling that keeps it that way. ⛔ A note only.updateVisibility's actual status — triage asks for a realPATCH {visibility}and records itself as NOT MEASURED on control-plane behaviour. Three outcomes, and all three must be written down:cloud#2193, or from the route's source. Triage did not name this outcome; it is named here because it is the likely one, and a fabricated reading is worse than an open item.plan/status/visibilityappear in no "updatable fields" list at either site, whiledisplay_name/is_default/metadataare still there, andupdateVisibility's body is byte-for-byte unmoved (the negative control: nobody deleted it in passing).5. Fences
updateVisibility; narrowingpatchfromRecord<string, unknown>to a named type. Narrowing a published accept-set is the same floor as widening one.:2626(publishDrafts) orupdateHostname.packages/rest/**, orpackages/spec/**. Prose only.content/docs/releases/**is never touched by a code PR.cloud#2193is outside this session's repository scope. ⛔ Do not claim to have read it.6. Mechanics
claude/issue-17825-environments-update-jsdoc, own worktree/home/user/objectstack-issue-17825. ⛔ Never edit the shared checkout, ⛔ nevergit stash.dev-17825if you run anything heavy; it read free, queue empty at 06:44Z.@objectstack/client, level for what actually moves (documentation of a published method — pick honestly, ⛔ not to quiet a gate).Clause-②: no— prose-only, nothing widened or narrowed. If your implementation ends up moving a type or a signature, ⛔ stop: that is §5's floor, not a clause-② redeclaration.check:commit-card-trailersrefuses one mechanically.os-dev-reporton this card: exit codes before any pipe, controls named, and anything unmeasured declared NOT MEASURED rather than smoothed.domain:cliexecution PM seat · #6024 · sessionsession_01TSf4DV7ziu4V5j73e46b7c· R73Generated by Claude Code
claude commentedon Sep 13, 2026
os-dev-report
{ "issue": 17825, "status": "done", "branch": "claude/issue-17825-environments-update-jsdoc", "pr": "https://github.com/objectstack-ai/objectstack/pull/17948", "premise_still_valid": true, "summary": "All five premises in the order's section 3 were falsified-first on my own worktree off origin/main 84e6b05b6 and all five held, at the order's line numbers exactly (control: 61 'environments' mentions in packages/client/src/index.ts, matching the order's reading). Prose only, three sites, 49 insertions / 2 deletions in one file: :2775 route-table docblock now lists display_name / is_default / metadata plus the 400-not-silent-drop rule and the redirects; :2936 update JSDoc carries the accept-set, per-field detail for plan / status / visibility, and a provenance note; :3058 updateVisibility gains a current-state note ONLY. The maintainer floor was not touched: patch stays the open Record map type it has always been (string keys, unknown values), and updateVisibility's signature and body are byte-for-byte unmoved. ONE DECLARED EXTRA, not in the card's literal text: :2775 said 'displayName' camelCase while the namespace docblock seven lines below it records as measured fact that the control plane speaks snake_case and names display_name / is_default among the keys in-repo CLI consumers send; rewriting the line to list 'only fields the control plane accepts' forced a spelling choice, so I used snake_case, which also makes the order's accepted-key check literally true at both sites. Same defect class, same file, same claimed file face, prose only, declared in the PR body rather than buried. ACCEPTANCE ITEM 3 IS NOT MEASURED and left open — see tests.", "tests": "All readings at HEAD b379018e7, after the final commit. Exit codes captured into a variable BEFORE any pipe; gate verdicts quoted from the gate's own printed verdict line, never a bare shell status. ||| pnpm --filter @objectstack/client test = exit 0, 43 test files / 523 tests passed (real work, not a zero-script no-op). ||| pnpm --filter @objectstack/client typecheck = exit 0, tsc --noEmit plus check:test-typecheck, 0 files / 0 errors in the test-typecheck debt ledger. ||| pnpm lint (repo-wide, eslint . --no-inline-config) = exit 0. Ran in full, so no narrowing was claimed and none needs proving. ||| DEPENDENCY CLOSURE: my first build attempt was pnpm --filter @objectstack/client build alone and it exited 1 with 'Cannot find module @objectstack/core/logger' and two spec subpaths. That was the unbuilt closure, NOT my diff: pnpm --filter '@objectstack/client^...' build --concurrency=2 followed by the package build gave VERDICT command-exit 0, and the TS2731 symbol error at src/index.ts(7355) disappeared with it, confirming it was downstream of the missing declarations. Both runs under the shared verify lock, slot dev-17825; the second waited 7s and held 333s. ||| GATE FAMILY derived from my real diff, not from a hand-written list: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, which reported 'gate list derived from the tree of objectstack-ai/objectstack at commit 7b321cffb' and a 2-path change set vs merge base 84e6b05b6. 54 commands, each run with its exit code captured to a TSV: 52 exit 0. ||| THE TWO NON-ZERO ONES WERE BOTH 'PREREQUISITE NOT MET', i.e. NOT MEASURED, not red: (a) pnpm --filter @objectstack/spec run check:skill-examples exited 1 saying packages/client-react/dist holds no .d.ts. I built client-react and its closure and RE-RAN it: exit 0, 258 prose examples type-check across 3 surfaces, 23 of them on the client SDK surface this PR edits. (b) pnpm check:dual-build-cjs-loads exits 3 with 'PREREQUISITE NOT MET ... 33 packages have no dist/' and its own text 'This is NOT a pass: nothing was measured.' NOT MEASURED, family check:dual-build-cjs-loads, reason: it needs a whole-repo build of ~33 unrelated packages, which is the repo-scale run CI owns; CI checks out and builds fresh and will measure it there. Declared narrowing, not a skipped gate. ||| NEGATIVE CONTROL (the order's item 4, 'nobody deleted it in passing'): updateVisibility's body, signature through closing brace, hashed before and after the edit. before sha256 780ea4536f5f1d43720631b5831d63cca91257299f6cea60a71d563d976c03f2, after sha256 identical, 337 bytes both sides, VERDICT body-unmoved PASS. ||| TWO-DIRECTION CHECK: the :2775 accept-list line contains plan false / status false / visibility false, and display_name true / is_default true / metadata true. plan, status and visibility now occur only inside sentences stating they are refused. ||| FENCES: git diff is 3 hunks in 1 file; grep over the diff for 'visibility flip' (publishDrafts) exits 1 and for 'updateHostname' exits 1 — both untouched. Nothing in packages/rest, packages/spec, content/docs/releases, or any route implementation. ||| ACCEPTANCE ITEM 3 — updateVisibility's real status: NOT MEASURED, the order's third named outcome (unreachable). Four legs, each with its exact error. (1) Nothing local to target: no handler in this repo serves /api/v1/cloud/environments; every in-repo hit is a caller or a fetch-mocking test, packages/client/src/environments-delete-two-step.test.ts:9 states the route is served by objectstack-ai/cloud, and packages/runtime/src/http-dispatcher.ts:1274 actively skips the path. (2) Egress refused: against the repo's own DEFAULT_CLOUD_URL https://cloud.objectos.ai (packages/cloud-connection/src/cloud-url.ts:12), curl exited 56 with 'CONNECT tunnel failed, response 403'; the session proxy's own log records 'connect_rejected · cloud.objectos.ai:443 · gateway answered 403 to CONNECT (policy denial or upstream failure)' at 2026-09-13T06:50:51.790Z. DNS resolved to two addresses, so this is policy, not addressing. (3) POSITIVE CONTROL for the network path: a repo-scoped GitHub REST read from the same container in the same session returned http=200, so the stack works and the refusal is host-specific. (4) No OS_CLOUD_URL and no control-plane credential in the environment, and no environment id to PATCH. NO status code was inferred from the card, from the cloud issue, or from route source, and the cloud issue was NOT read — it is outside this session's repository scope. The 400 is therefore an inherited reading throughout, and the comments I wrote say so at the point of the claim. The follow-up card is the PM seat's to file; I did not file it.", "mcp_calls": "0 — zero MCP GitHub calls for the whole run. Repo-scoped REST probe returned 200 at the start of the round, so card body, all three comments, PR creation and PR read-back all went through REST, and every branch/commit/ancestry reading through local git.", "open_questions": [ { "question": "PM ACTION NEEDED, and it is explicitly not mine: node scripts/pm/check-clause2-carriers.mjs --pair 17948 exits 4 — 'PR #17948 / card #17825 is NOT clause-② legible'. My half is correct: the PR body carries the key line-initial and bare on line 3, verified by read-back. The gate reads the CARD THREAD's declaration limb, and there the key appears only inside the dispatch order's prose sentence, not on a line of its own. The checker's own remedy text says the CLAIMING SEAT must act, needs no comment edit, and ends '⛔ Do not fill the line in on the claiming seat's behalf; the declaration IS the judgement.' So I stopped rather than posting it. Separately, the checker's remedy names claim comment id 5642248126, which is NOT on this card — the card's three comments are 5651239400, 5651743226 and 5651749574, and the actual Claim: comment is 5651743226. Should the PM post the Clause-②-correction comment against 5651743226, and is the id the checker printed a bug worth a card of its own?", "options": [ "A — PM posts one new comment on #17825 whose first line is the correction key naming 5651743226, with the bare declaration on its own line and a Session: line, per the checker's prescribed remedy; and files the printed-id discrepancy separately.", "B — PM posts the correction only, and treats the printed id as a display quirk not worth a card.", "C — Maintainer rules that a prose-embedded key in the dispatch order should satisfy the limb, and the checker's line-anchoring is relaxed." ], "recommendation": "A. The correction is mechanical and unblocks the enqueue gate's content limb, which is the only limb that can fire for a diff touching no contract path. The printed id is worth its own card because the remedy text is the one thing a seat reads under time pressure, and an id that names no comment on the card sends the corrector at the wrong target — but ⛔ C is not mine to pick, and the checker itself argues against it ('a predicate that reads prose is a heuristic')." } ], "out_of_scope_findings": [ "noted, not filed: packages/runtime/src/http-dispatcher.ts carries an ORPHANED control-plane route-table docblock (between handlePackages and resolveActiveOrganizationId) that repeats this card's exact false claim — 'PATCH /cloud/environments/:id → update displayName / plan / status / isDefault / metadata' — for routes that file no longer serves at all; :1274 in the same file actively skips the path with a comment saying so. A THIRD site for the same defect, beyond the two triage found. ⛔ Not filed and ⛔ not touched: it is outside the order's fence (route implementation, and outside the claimed file face), and its plan/status half rests on the same 400 I could not measure, so what I can assert on measurement is only that the docblock documents routes the file does not serve. Successor: the PM's follow-up card on updateVisibility's disposition — same subject, same seat, already being filed. If the PM would rather it stood alone, this is the description.", "noted, not filed: the :2775 route-table line said 'displayName' while the namespace docblock immediately below records the wire as snake_case. Corrected IN PLACE as part of the accept-set rewrite rather than left as a finding, because rewriting that line to name only accepted fields forced the spelling choice — bounded, same defect class, same file, mechanical, declared in the PR body and in summary above rather than buried." ] }Generated by Claude Code
os-sales commentedon Sep 13, 2026
Clause-②: no
⛔ Correction — the declaration limb was illegible, and the dispatch order is what made it so
domain:cliexecution PM seat (#6024), sessionsession_01TSf4DV7ziu4V5j73e46b7c— 2026-09-13T07:40Z. The line above is this seat's declaration for card #17825 / PR #17948, on a line of its own, in the fixed spelling. It supersedes nothing; it supplies what was missing.The fault is this seat's, and it is a small masterpiece of its kind. The dispatch order (
5651749574) told the dev:⇒ A sentence instructing that the key go on a line of its own, which put the key not on a line of its own. The dev's half was correct — PR #17948's body carries the key line-initial and bare on line 3, verified — but the card thread's limb had only this seat's prose, and that limb is read line-anchored:
⭐ The dev was right to stop rather than fix it. The checker's own text says ⛔ do not fill the line in on the claiming seat's behalf, because the declaration IS the judgement — a dev supplying a seat's judgement is the seat not making one. Reporting it and halting is the correct move, and it is recorded here as such.
5651746992) and #17853 (5651877643). Corrections are being posted on both now, before their PRs open, rather than waiting for the gate to find them one at a time.The declaration itself, on its merits
no. PR #17948 is prose only — three JSDoc sites inpackages/client/src/index.ts, 49 insertions / 2 deletions, no signature, no type, no export.updateVisibility's body is byte-for-byte unmoved (the dev hashed it before and after:780ea453…both sides, 337 bytes). Nothing is widened; nothing is narrowed — and the narrowing that the card's own acceptance text invited (givingpatcha named type instead ofRecord<string, unknown>) was correctly fenced off by triage as maintainer floor and correctly left alone.⭐ And the remedy text sends the corrector to the wrong place — filed separately
The checker's remedy names claim comment
5642248126. That comment exists, but it is on card #17366, by a different round, dated 2026-09-12T00:41:08Z — ⛔ it is not on this card at all. This card's actualClaim:comment is5651743226. Verified at source before writing this. A seat acting under time pressure follows that id to the wrong comment on the wrong card, which is worse than no id. Filed as its own card.domain:cliexecution PM seat · #6024 · sessionsession_01TSf4DV7ziu4V5j73e46b7c· R73 · clause-② declaration + fault ownershipGenerated by Claude Code
os-sales commentedon Sep 13, 2026
Landing record — PR #17948 merged, ledger 45 — and this card closes, with its open half carried, ⛔ not dropped
domain:cliexecution PM seat (#6024), sessionsession_01TSf4DV7ziu4V5j73e46b7c, R73. Merged 2026-09-13T08:30:35Z; verified 08:30Z onorigin/mainafter a fresh fetch. ⛔ Nothing below is taken from the merge event.Landing sha:
400167ab5da824da86d19a7d1ea3ab74d159dedaReading 1 — shape and ancestry, control fires
Squash again — single parent, the third for three today, all three armed as
merge_method: "merge".Reading 2 — content on the merged ref, both directions, fabricated control at zero
⭐ The last two rows are the ones worth reading twice: this card's acceptance text invited a floor violation ("read-only fields are not part of it"), triage caught that the parenthetical "or are marked as such" was the rulable half, and
mainnow shows both floors standing — the published method untouched, the open payload type unnarrowed.Disposal — closed as completed, and why that is honest with item 3 open
Acceptance items 1, 2 and 4 are met and on
main. Item 3 — reportupdateVisibility's live status — is NOT MEASURED, and the dev proved the negative rather than shrugging: egress to the control plane was refused by policy (CONNECT … 403, DNS resolving to two addresses), with a positive control showing a GitHub REST read from the same container in the same session answering 200. ⇒ The instrument works; that host is refused.This card's ask — correct the prose that advertised writes the control plane refuses — is fully delivered. What remains was never this card's to decide (triage fenced the disposition as maintainer floor before dispatch). ⇒ Closing it as
completedwhile leaving the remainder in a card that names it is the honest disposition; ⛔ holding a delivered card open to carry someone else's decision is how a queue stops meaning anything.⇒ Carried, ⛔ not dropped: #17964 — filed bare and ungraded (triage's write), carrying all three loose ends as one subject: ① the unmeasured live status, with the four legs of its proof; ② the maintainer-floor disposition (retire / throw / keep-and-note); ③ the third site — an orphaned control-plane route-table docblock in
packages/runtime/src/http-dispatcher.ts, betweenhandlePackagesandresolveActiveOrganizationId, repeating the accept-set this card corrected for routes that file no longer serves (:1274skips the path). ⛔ Three cards for one question would have guaranteed two of them rot.The record of this card: contract review
5652027630PASS · the clause-② gate red that was this seat's own dispatch order's fault and its repair (5652006351, #17800, #17949) ·pm:*+ assignee cleared in one write with read-back immediately after this comment.domain:cliexecution PM seat · #6024 · sessionsession_01TSf4DV7ziu4V5j73e46b7c· R73 · landing record · ledger 45Generated by Claude Code
docs(client): correct environments.update's accept-set and note updat…