metadata: the declared save option sortKeys is honoured by the json and yaml formats but silently ignored by the default typescript format #19872

Activity

1. objectstack-fleet commented on Sep 23, 2026

   

   objectstack-fleetbot

   on Sep 23, 2026

   ContributorAuthor

   More actions

   定级 pm:queue · priority:p3 · bug · domain:engine —— sortKeys 在默认的 typescript 格式下被静默忽略

   Path: platform-core

   Triage: lands in packages/metadata/src/serializers/typescript-serializer.ts (never reads options.sortKeys) ⇒ domain:engine; rationale: a declared save option is honoured by json / yaml and silently dropped by typescript, which is FilesystemLoader.save()'s default format, so a caller asking for deterministic key order gets unsorted keys with no signal; the cost is noisy diffs of saved files, not wrong data ⇒ p3; PR #19865 (same file) has landed, so the site is free.

   分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ),2026-09-23T15:24Z。本席读完了卡面(本卡尚无评论)。

   本席的读数(origin/main dabf8d795e)

   • sortKeys 出现次数:typescript-serializer.ts 0,json-serializer.ts 2,yaml-serializer.ts 2。
   • metadata-persistence.zod.ts:273 声明了 sortKeys: z.boolean().optional();filesystem-loader.ts:413 默认 format = 'typescript'。
   • 卡面说要排在 PR fix(metadata): TypeScriptSerializer annotates each item with its own metadata type's spec type, never ServiceObject for a non-object #19865 之后:该 PR 已落地(e9eb2244d5,TypeScriptSerializer.serialize() annotates every item as ServiceObject whatever its metadata type — a saved view (or any non-object kind) is written as a .ts file that fails tsc with TS2353 #19852),⛔ 不再挂阻塞。

   与卡面一致。

   判定

   • 业务后果:把元数据存到文件、要求 sortKeys: true 的人,在默认格式下拿到的键顺序没有排,也没有任何提示。这个选项本来就是为了让保存下来的文件 diff 稳定。
   • p3:声明了却不生效(北极星第 4 条「错的必须响亮」),但只影响键顺序,⛔ 不影响数据内容。
   • 修法方向(⛔ 不是裁定,卡面已写):对 typescript 格式包着的那段 JSON 正文用与 JSON 序列化器相同的排序;或者对这个格式响亮地拒收 sortKeys。要去掉的是「静默接受」。

   ---

   Generated by Claude Code
2. objectstack-fleet

   added

   bugSomething isn't workingSomething isn't working

   domain:engine

   pm:queue

   priority:p3

   pm:dispatched

   and removed

   pm:queue

   on Sep 23, 2026
3. objectstack-fleet

   assigned

   huangyiirene

   on Sep 23, 2026
4. objectstack-fleet commented on Sep 23, 2026

   

   objectstack-fleetbot

   on Sep 23, 2026

   ContributorAuthor

   More actions

   Claim: PM loop round 21
   Session: session_01TEhopqrWQYBycZzyJHpAZr
   Branch: claude/issue-19872-ts-serializer-sortkeys
   Worktree: objectstack-issue-19872
   Domain: domain:engine
   Seat: domain:engine#1
   File surface: packages/metadata/src/serializers/typescript-serializer.ts, its tests under packages/metadata/src/serializers/, the TypeScriptSerializer paragraph of packages/metadata/README.md if it states option handling, one .changeset/*.md (stop on breach; explain in the report). ⛔ No change to any declaration reachable from an @objectstack/metadata exports entry
   Container & model: S, mode:subagent, model: sonnet (no path-derived mandate; floor tier — a declared option the other two formats already honour)
   Clause-②: no
   Thread-read: none
   Serial constraints cleared: PR #19865 (#19852), which edited typescript-serializer.ts, landed as e9eb2244d5. No open PR and no in-flight claim touches packages/metadata/src/serializers.

   Written 2026-09-23T15:53Z. North Star clause 3 read this act: product P0/P1 are open. This card is a product defect (a declared save option silently ignored by the default format), not a tooling or contract-hygiene card, so it is dispatchable at p3.

   Why Clause-②: no: sortKeys is already declared and honoured by the json and yaml formats; the typescript format starts honouring it. No accept set widens and no public surface moves.

   ---

   Generated by Claude Code
5. objectstack-fleet commented on Sep 23, 2026

   

   objectstack-fleetbot

   on Sep 23, 2026

   ContributorAuthor

   More actions

   os-dev-report

   {
   "issue": 19872,
   "status": "done",
   "branch": "claude/issue-19872-ts-serializer-sortkeys",
   "pr": "#19901",
   "session": "session_01TEhopqrWQYBycZzyJHpAZr",
   "premise_still_valid": true,
   "summary": "A1: reproduced on origin/main (dabf8d7) — sortKeys:true sorted the json output's keys and left typescript's unsorted; javascript (same TypeScriptSerializer class, same renderModule() code path) is affected identically and is fixed by the same code change (pinned separately). A2: JSONSerializer's sort is deep/recursive (recurses into nested objects; arrays keep element order) — matched exactly, not approximated as top-level-only. .d.ts diff: built @objectstack/metadata on origin/main (dabf8d7, via a comparison worktree) and on this branch's head (67015fe), diffed every exports entry's emitted .d.ts (., ./node, ./migrations, ./errors, ./view-container) — identical for 4/5; index.d.ts (and node.d.ts, which re-exports it, also checked identical) differ by exactly one added JSDoc comment on JSONSerializer's pre-existing private sortObjectKeys member, no declaration line changed, class shape unchanged. Implementation: extracted JSONSerializer's recursive key sort into a new package-internal packages/metadata/src/serializers/sort-object-keys.ts (not re-exported from any @objectstack/metadata exports entry). TypeScriptSerializer's renderModule() — the one function both the public serialize() and the package-internal serializeTypeScriptForMetadataType() call — now sorts its JSON body with that same shared function when options.sortKeys is true; sortKeys absent/false takes the untouched path (byte-identical output). JSONSerializer's own private sortObjectKeys() is kept as a thin delegate to the shared function (rather than deleted) specifically so its declared shape, and the package's emitted .d.ts, stay unchanged apart from the added comment. Added a patch changeset for @objectstack/metadata. packages/metadata/README.md's TypeScriptSerializer paragraph is silent on which SerializeOptions it honours (no false sortKeys claim to correct), so left unedited per the file surface's own stated condition.",
   "tests": "pnpm --filter '@objectstack/metadata^...' build (dependency closure): exit 0. pnpm --filter @objectstack/metadata build on both origin/main (dabf8d7, in a throwaway comparison worktree) and HEAD (67015fe): exit 0 both, .d.ts diffed as described above. pnpm --filter @objectstack/metadata test: 54 files / 821 tests passed, exit 0 — includes new describe('sortKeys (#19872)') in serializers.test.ts (7 tests: sortKeys:true through serialize(), serializeTypeScriptForMetadataType(), and the javascript format, each byte-identical to JSONSerializer's own sorted output; sortKeys absent/false byte-identical to origin/main through both direct calls and FilesystemLoader.save(); a serialize/deserialize round trip with sortKeys:true for view and object; FilesystemLoader.save() honouring sortKeys:true for object through the loader path, A3). pnpm --filter @objectstack/metadata typecheck: exit 0. Ablation (fix committed first, at 67015fe): reverted json-serializer.ts + typescript-serializer.ts to origin/main's version and removed the new sort-object-keys.ts, ran vitest run src/serializers/serializers.test.ts -t 'sortKeys (#19872)' — 4 failed (every sortKeys:true pin) / 3 passed (byte-identity-off + round trip, order-insensitive) / 23 skipped, exit 1 as expected; restored with git checkout HEAD -- <3 files>, verified git diff HEAD empty and git hash-object == git rev-parse HEAD:<path> for all three files; rebuilt, exit 0. Gates: node scripts/pm/dispatch-gates.mjs --commands on the final commit (67015fe) derived 59 families; ran all 59 with exit codes captured before any pipe (cmd > log 2>&1; code=$?), reconciled with --ran <file recording 'cmd :: exit N'>: '59 derived famil(ies) accounted for — 56 run, 3 NOT-MEASURED (3 DERIVED from a recorded exit 3)'. The 3: pnpm check:dual-build-cjs-loads, pnpm check:lean-entry-closure, pnpm check:type-check-debt — each exits 3 and self-declares 'PREREQUISITE NOT MET ... this is NOT a pass and NOT a finding: nothing was measured', needing a full pnpm build/turbo run build across the whole ~82-package monorepo (dist for packages far outside @objectstack/metadata's dependency closure, e.g. objectql, runtime, the apps) — outside the local dependency-closure build scope; CI's Build Core / Type Check jobs cover these. The other 56: exit 0. Also ran the live verdict (the known dispatch-gates gap: its check:issue-citations family runs only --self-test): node scripts/check-issue-citations.mjs — exit 0 ('every citation this change adds resolves').",
   "mcp_calls": "5 — mcp__github__issue_read (method: get_comments, on #19872), mcp__github__issue_read (method: get, on #19872), mcp__github__pull_request_read (called with an invalid pullNumber before I had the PR number; client-side InputValidationError, no server call made), mcp__github__pull_request_read (method: get, on #19901, to verify the body wrote back verbatim), mcp__github__list_pull_requests (to find PR #19901 by head branch). All five are reads; zero MCP write tools were used.",
   "api_writes": "2 — POST /repos/objectstack-ai/objectstack/pulls (op pr_create, draft:true, via scripts/pm/with-fleet.sh --via dispatch, relay run 35888473148, conclusion success) and POST /repos//issues/19872/comments (this report, same relay). git push (the empty-branch probe and the real commit) is not a REST write and did not go through the relay, per the branch's own routing rule.",
   "open_questions": [],
   "out_of_scope_findings": []
   }
6. objectstack-fleet commented on Sep 23, 2026

   

   objectstack-fleetbot

   on Sep 23, 2026

   ContributorAuthor

   More actions

   ACCEPT — round 21 · PR #19901 · Fixes

   domain:engine#1, session_01TEhopqrWQYBycZzyJHpAZr, written 2026-09-23T16:42Z. Every reading below was taken against GitHub and origin/main in this act, ⛔ not from the dev's report.

   check	reading
   head	67015feb5f
   PR shape	draft → main; first body line Fixes #19872; no other closing keyword; Clause-②: no at column 0, agreeing with the patch changeset
   scope	5 files: JSONSerializer's recursive key sort moved verbatim into a package-internal sort-object-keys.ts (the private method kept as a thin delegate so the class's declared shape is unchanged), renderModule() sorts the JSON body when sortKeys is true, tests, one changeset
   reach	the javascript format shares the class and the path and is fixed by the same change; both serialize() and the loader's internal path honour the option
   byte-identity	sortKeys absent or false: 28/28 format × path combinations byte-identical to the base (contract reviewer's measurement on built dists)
   published surface	the emitted declarations of all 5 exports entries differ only by one comment; sort-object-keys.ts is reachable from none
   ablation	reverting the fix reds exactly the four sortKeys: true pins
   governed	NOT governed (check-governed-merges --pr 19901)
   contract review	PASS on this head (5798812881)
   CI	every check success or a roster skip on this head before ready

   Out-of-scope findings — dispositions: none reported by the dev. The contract reviewer's flags are all acceptable as they stand: yaml's key order differs from json's only for integer-like keys (pre-existing), and packages/metadata/README.md credits key sorting to JSONSerializer alone (an understatement, not false) → Acceptance notes.

   Process note: the dev's final report omitted the files_changed, deviations and structured gates fields os-dev.md requires; the seat read the file list from the diff and the gates from the report's prose.

   Landing: ready → queue on this head once CI is fully green.

   ---

   Generated by Claude Code
7. objectstack-fleet

   closed this as completedin #19901on Sep 23, 2026
8. objectstack-fleet

   removed

   pm:dispatched

   on Sep 23, 2026
9. akarma-synetal

   added a commit that references this issue on Sep 28, 2026

   fix(metadata): honour sortKeys in the typescript/javascript serializer (

   ...

   This issue will close once commit d1ca874 is merged into the 'main' branch.

   d1ca874