fix(service-storage): stop handing out _local/file/:key, a URL nothing mounts (#3641)

[os-zhuang]

Closes #3641.

Three call sites built ${basePath}/_local/file/<key>. No registrar has ever mounted it, so anyone following one got a 404. The tranche-3 storage ledger (#3636) recorded the URL as deliberately absent and filed this; now nothing builds it either.

Each site, fixed according to what it could honestly do

LocalStorageAdapter.getPresignedUpload() — omits downloadUrl (optional on the descriptor) rather than emitting a fake one. It cannot construct the real capability URL: that is keyed by sys_file.id, and an adapter only ever sees the storage key.

Nothing read the field, which is exactly how it survived. The presigned-upload route builds its own downloadUrl (${basePath}/files/:fileId/url) and ignores this one, and all three real readers of desc.downloadUrl take it from getPresignedDownload — whose URL is mounted (_local/raw/<token>). A write-only field pointing at nothing.

GET /files/:fileId/url and GET /files/:fileId — answer 501 NOT_IMPLEMENTED when the adapter has neither getPresignedDownload nor getSignedUrl, instead of returning (or 302-ing to) the unmounted URL. The caller learns the adapter is the limitation rather than chasing a broken link.

Blast radius

Confined to adapters implementing neither capability. LocalStorageAdapter and the S3 adapter both implement getPresignedDownload, so no shipped path changes. For the remaining case, a 200/302 pointing at a 404 becomes a 501 that says why — strictly more informative, and the same NOT_IMPLEMENTED code the raw routes already use for unsupported adapters.

Tests

@objectstack/service-storage — 198 passed (17 files), up from 196: two new conformance cases for the 501 branches. Mutation-checked — restoring either dead URL fails them.

On typecheck, precisely

This package has no typecheck script, and CI's TypeScript gate runs pnpm --filter @objectstack/spec exec tsc --noEmit — spec only. A bare tsc --noEmit here reports 39 pre-existing errors, 7 of them in test files this change never touches (the repo-wide .js-extension style under node16 resolution).

I am neither fixing those (unrelated, 39 files of churn) nor claiming this package typechecks clean. Flagging it because I had been reporting "typecheck clean" on packages that do have the script, and it would be easy to read that as a repo-wide property. It isn't.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K35y3ovfWtCkBHYFCqUfAt

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 28, 2026 1:21am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/packages.mdx (via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.