[objectstack-fleet]

Requested by Leehom · project thread

Fixes #31196

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:元数据按名读取的缓存出口(默认的 GET /api/v1/meta/:type/:name)里,Last-Modified 不再填「这次读取的时间」。条目来自 sys_metadata 存储行时,填该行的 updated_at(最近一次保存或发布的时间);条目来自代码或文件、平台不知道它何时改过时,不发这个头。
• 为什么改:同一条没改过的元数据,两次读到的 Last-Modified 不一样而 ETag 相同,这个头在说假话,还让 Queue-flake anchor: src/domains/mcp-object-schema-mask.test.ts #31171 的测试在合并队列里抖过两次。
• 风险与回滚:只改头的取值;ETag、Cache-Control: private, no-cache、If-None-Match 的 304 全部不变,按名读取的响应信封逐字节不变(时间走进程内不可序列化的符号,不进 JSON)。回滚即 revert。
• 先看:packages/metadata-protocol/src/protocol-meta-item-reads.ts(采用存储行处记下 updated_at,返回信封时挂上);packages/metadata-protocol/src/protocol-search-and-cache.ts(lastModified 改读它,没有就不给键);新文件 served-row-changed-at.ts。
• 两分钟验证:pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.cached-item-last-modified.test.ts,预期 4 个用例全过:两次读同一个时间、保存和发布各自推进它、代码条目没有 lastModified 键。
• 需要你做的:无,席位落地。

What changes

• getMetaItemCached (protocol-search-and-cache.ts) answered lastModified: new Date().toISOString(), the time of the read. It now answers the change time of the stored sys_metadata row the item is served from, and no lastModified key when no stored row serves it. The REST door already renders Last-Modified only when the key is present (meta-item-read-routes.ts, unchanged), so a code-shipped item answers no header.
• The time is known in one place: the by-name read (readMetaItem, protocol-meta-item-reads.ts) holds the row it adopts as the item's content. It records canonicalIsoInstant(row.updated_at ?? row.created_at) on its active-state envelope as a non-enumerable Symbol.for key (served-row-changed-at.ts, the stored-row-binding.ts pattern). JSON.stringify drops it and a spread does not copy it, so the published GetMetaItemResponseSchema envelope, its REST and MCP answers, and every toEqual pin are unchanged. The cached read asks servedRowChangedAtOf(result).
• canonicalIsoInstant in sys-metadata-repository.ts is now exported (module-internal; index.ts does not re-export it), so the read uses the repository's one spelling of a driver timestamp.
• Changeset .changeset/31196-cached-meta-item-last-modified.md: @objectstack/metadata-protocol patch. @objectstack/rest gains a test only.

Tests

• packages/metadata-protocol/src/protocol.cached-item-last-modified.test.ts (real protocol, stub sys_metadata store, fake Date moved minutes between steps):
  • §1 two reads of one unchanged stored item (5 and 9 minutes after the save) both answer the save time; CONTROL: same ETag, cacheControl ['private','no-cache'].
  • §2 a save moves it to the save time; a pending draft does not move it; a publish moves it to the publish time; CONTROL: each change also moves the ETag.
  • §3 a code-shipped item (registry, no stored row) has no lastModified key; CONTROL: it keeps its ETag and cacheControl.
  • §4 the change time is not in the by-name read's serialised envelope.
• packages/rest/src/meta-item-cached-last-modified.test.ts (the door, protocol double): renders the protocol's time as Sat, 07 Nov 2026 08:00:00 GMT and the same on a second read; sends no Last-Modified when the key is absent while ETag and Cache-Control stay; If-Modified-Since answers 200 with the body, with or without a time.

Ablation (os-dev, via node scripts/ablation-replace.mjs, the test resolves the protocol from src/): anchor ...(lastModified !== undefined ? { lastModified } : {}), replaced by lastModified: new Date().toISOString(), (anchor 1 → 0, replacement 0 → 1, blob c29eebfc → c033ddc6), then the pin file:

Ablation red: 3 failed | 1 passed (§4 stays green, as predicted: it reads the by-name envelope, not the cached answer)

 ❯ src/protocol.cached-item-last-modified.test.ts (4 tests | 3 failed) 82ms
     × §1 two reads of one unchanged stored item answer the same lastModified — the save time 48ms
     × §2 a save moves it, and so does a publish 26ms
     × §3 an item no stored row serves has no known change time: no lastModified key 4ms
AssertionError: expected '2026-11-07T08:05:00.000Z' to be '2026-11-07T08:00:00.000Z' // Object.is equality
AssertionError: expected [ Array(5) ] to not include 'lastModified'
ablation-replace: ok restored: blob == HEAD (c29eebfc85db) and `git diff HEAD` is empty

Acceptance notes

• Mechanism, measured on origin/main 66bf5b4. The order's hypothesis holds: the producer stamped the read time and the REST door only rendered it. The door needed no change.
• Where the change time is reachable. Not at getMetaItemCached: its only input is getMetaItem's envelope, whose version is a hash digest of the stored head (readVersionToken → receiptVersion), not a time. The row is in hand inside readMetaItem, so the file surface grew past the claim's by protocol-meta-item-reads.ts, the new served-row-changed-at.ts, a one-word export in sys-metadata-repository.ts, and the engine-double ledger row for the new test (scripts/engine-double-contract.pinned.json, written by check-engine-double-contract.mjs --write).
• What counts as the item's change time. The adopted row's updated_at, which SysMetadataRepository stamps on every write of the row, a save and a publish alike (§2 measures both), created_at for a row without one. A stored row the read declines (a shipped flow name's row, ADR-0146 D9) does not lend its time: the served item is then the code's, and answers none.
• Boundary, stated rather than hidden. A stored object's served body also carries code-side contributions folded at read time (extend fields from installed packages, the artifact's lock envelope). Installing a package that changes them moves the ETag but not this Last-Modified, which states the stored row's change as the card's ruling names it. Nothing judges freshness from it: the ETag does (no-cache).
• If-Modified-Since, measured. The door forwards it as cacheRequest.ifModifiedSince; the protocol never reads that member, and the door's own 304 compares If-None-Match only. So no request is answered 304 from a time, before or after this change; the REST pin records it.
• Precision. Last-Modified is whole seconds (toUTCString()), so two writes within one second share a header value; the ETag still separates them.
• Not touched, carrier: seat. packages/runtime/src/domains/mcp-object-schema-mask.test.ts (PR test(runtime): hold clock-derived header values fixed in the /meta action-entry wire comparison #31195) masks last-modified with a comment saying the protocol stamps the read time. After this PR that sentence is false for Last-Modified (the Date header half still holds); the masking itself stays harmless. Outside the claimed surface.

Verification

Head 7ff2b9e5. origin/main was merged once before the PR, a no-op at 66bf5b4; main has since moved to 30f23fe, and none of its 141 changed files is one this PR touches (one other packages/metadata-protocol test file).

• pnpm --filter @objectstack/metadata-protocol test (on f59f3fa+565bea38; the two later commits change only the two new test files and the ledger row, and both pin files were re-run green on 7ff2b9e: 4/4 and 3/3): Test Files 323 passed | 4 skipped (327), Tests 22531 passed | 26 skipped (lock VERDICT command-exit 0).
• pnpm --filter @objectstack/rest test: Test Files 394 passed (394), Tests 7489 passed | 332 skipped (VERDICT command-exit 0).
• pnpm --filter @objectstack/metadata-protocol --filter @objectstack/rest typecheck: exit 0 (metadata-protocol's tsc includes src/**/*, the new test listed by --listFiles; rest runs check:test-typecheck, 0 errors).
• Lint, scoped: node --stack-size=4000 node_modules/eslint/bin/eslint.js packages/metadata-protocol packages/rest --no-inline-config, exit 0.
• Derived gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack named 69 families for this diff; all 69 ran on 7ff2b9e5, exit 0 each. --ran: "69 derived famil(ies) accounted for — 69 run, 0 NOT-MEASURED". check-plugin-teardown-shape --self-test needed git fetch --depth=1 origin 621a4876 on this shallow clone first.
• Earlier rounds of the same union were red on the new test doubles only, each fixed in the test: check:engine-double-contract (ledger rows written with --write), check:objectql-double-limit (the find double now honours limit), check:where-matcher (the matcher refuses $ combinators), check:test-source-alias (module-top preloads: ./lint-root-preload.testkit.js and @objectstack/objectql).
• CI families are read from this PR's check-runs, not re-run here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 6 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/services-checklist.mdx (via getMetaItemCached (symbol, a method of class ProtocolSearchAndCacheFacet))

What this run could not see

• the SDK route bridge reached 63 of 226 client-bound route-ledger rows — the other 163 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 163: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 10 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 0d0c377beb988b990e77aa4763fd5e4b429d8de4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from da3ef679fbcdaf369f0f08285eb49f5ecdd14f42 — the merge of head 7ff2b9e528edafe5baf30284f84939be5127e926 into base 0d0c377beb988b990e77aa4763fd5e4b429d8de4, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin da3ef679fbcdaf369f0f08285eb49f5ecdd14f42 && git checkout da3ef679fbcdaf369f0f08285eb49f5ecdd14f42
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0d0c377beb988b990e77aa4763fd5e4b429d8de4 7ff2b9e528edafe5baf30284f84939be5127e926 && git checkout -B drift-repro 0d0c377beb988b990e77aa4763fd5e4b429d8de4 && git merge --no-ff 7ff2b9e528edafe5baf30284f84939be5127e926

node scripts/docs-audit/affected-docs.mjs --json 0d0c377beb988b990e77aa4763fd5e4b429d8de4

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 0d0c377beb988b990e77aa4763fd5e4b429d8de4 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5o8PE7ZtVjcor51wBZ

维护者速读

• 改了什么:元数据按名读取的缓存出口(默认的 GET /api/v1/meta/:type/:name)里,Last-Modified 不再填「这次读取的时间」。条目来自 sys_metadata 存储行时,填该行的 updated_at(最近一次保存或发布的时间);条目来自代码或文件、平台不知道它何时改过时,不发这个头。
• 为什么改:同一条没改过的元数据,两次读到的 Last-Modified 不一样而 ETag 相同,这个头在说假话,还让 Queue-flake anchor: src/domains/mcp-object-schema-mask.test.ts #31171 的测试在合并队列里抖过两次。
• 风险与回滚:只改头的取值;ETag、Cache-Control: private, no-cache、If-None-Match 的 304 全部不变,按名读取的响应信封逐字节不变(时间走进程内不可序列化的符号,不进 JSON)。回滚即 revert。
• 先看:packages/metadata-protocol/src/protocol-meta-item-reads.ts(采用存储行处记下 updated_at,返回信封时挂上);packages/metadata-protocol/src/protocol-search-and-cache.ts(lastModified 改读它,没有就不给键);新文件 served-row-changed-at.ts。
• 两分钟验证:pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.cached-item-last-modified.test.ts,预期 4 个用例全过:两次读同一个时间、保存和发布各自推进它、代码条目没有 lastModified 键。
• 需要你做的:无,席位落地。

席位意见:接受。Last-Modified 现在取条目所服务的存储行的 updated_at,代码随包发布的条目不发这个头;只改元数据协议这一层,REST 入口不动,新鲜度仍只由 ETag 决定。

席位核对 — ACCEPT · domain:server#5 · Head-sha 7ff2b9e528edafe5baf30284f84939be5127e926 · 2026-11-07T20:09Z

• Shape: 8 files, +431/−4, read from the diff. readMetaItem records the adopted sys_metadata row's updated_at (else created_at, through the repository's own canonicalIsoInstant, now exported) on its envelope as a non-enumerable Symbol.for property (served-row-changed-at.ts); getMetaItemCached answers it, or no lastModified key. Draft reads and items no stored row serves carry none. The symbol never serialises, so GetMetaItemResponseSchema answers and every REST/MCP pin are unchanged; a spread copy loses it, which omits the header (the safe direction). meta-item-read-routes.ts untouched.
• Premise measured: on main the cached read set lastModified: new Date().toISOString(); the dev's ablation (read time put back) reds 3, CONTROL green.
• Pins: two reads of one unchanged stored item answer the same Last-Modified; a save moves it; a code-shipped item answers no header; ETag / Cache-Control: no-cache unchanged (REST-level test in packages/rest).
• Gates: head check-runs 35 success, 13 skipped, none red or pending. check-expected-skips: OK, all 13 in main's roster (exit 0). No governed path, 435 changed lines ≤ 3000. The dev's dispatch-gates --commands: 69 derived, 69 run, all exit 0. Mergeable state clean.
• Accepted deviations: surface beyond the claim (protocol-meta-item-reads.ts, new served-row-changed-at.ts, the one-word export in sys-metadata-repository.ts, the engine-double ledger rows from its gate's own --write): the change time is reachable only inside readMetaItem. origin/main merged once at 66bf5b4a; main has moved since, touching none of these files, and the queue builds on current main.
• Out of scope: the CLOCK_HEADERS comment in runtime's mcp-object-schema-mask.test.ts (test(runtime): hold clock-derived header values fixed in the /meta action-entry wire comparison #31195) now overstates for Last-Modified: a comment-only follow-up, carried by this seat. Clause-②: no (the field is already optional in the published http-cache.zod.ts), Metadata-protocol: none, Skills-docs: n/a. Changeset patch.
• Landing: ungoverned. Fixes #31196. Ready + auto-merge.