feat(runtime): package-scoped single-item metadata resolution via ?package= (ADR-0048)

REST single-item GET /meta/:type/:name now passes its `?package=` query into
`getItem(type, name, currentPackageId)` — the package-scoped (prefer-local)
resolution added with the namespace gate. Single-item fetch was previously
context-free (only list + protocol paths were package-aware).

Enables package-scoped single-doc resolution (doc content lives only on the
single-item endpoint), so `doc` names no longer need a namespace prefix for
uniqueness — prefix demoted to a recommended convention (doc.zod comments
updated), matching page/dashboard/report.

Verified: curl `/api/v1/meta/doc/showcase_index?package=com.example.showcase`
returns the doc with content; the package param reaches getItem's 3rd arg.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/adr-0048-meta-getitem-package.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/runtime": minor
+"@objectstack/spec": minor
+---
+
+feat(runtime): package-scoped single-item metadata resolution via `?package=` (ADR-0048)
+
+The REST single-item GET `/meta/:type/:name` now threads its `?package=` query
+into `getItem(type, name, currentPackageId)` (the package-scoped resolution
+added in the namespace-gate work). Previously only the *list* and the protocol
+path were package-aware; a single-item fetch was context-free.
+
+This lets a caller resolve one item scoped to a package — notably the doc
+viewer (`/apps/:packageId/docs/:name`), whose content lives only on the
+single-item endpoint. As a result, `doc` names no longer need a namespace
+prefix for uniqueness (the prefix becomes a recommended convention, like
+`page`/`dashboard`/`report`); `doc.zod` doc-comments updated accordingly.

packages/runtime/src/http-dispatcher.ts

@@ -1173,7 +1173,9 @@ export class HttpDispatcher {
                 const metaSvc = await this.resolveService('metadata', _context.environmentId);
                 if (metaSvc && typeof (metaSvc as any).getItem === 'function') {
                     try {
-                        const data = await (metaSvc as any).getItem(singularType, name);
+                        // ADR-0048 — thread `?package=` so single-item resolution is
+                        // package-scoped (prefer-local), matching list resolution.
+                        const data = await (metaSvc as any).getItem(singularType, name, packageId);
                         if (data) return { handled: true, response: this.success(data) };
                     } catch { /* not found */ }
                 }

packages/spec/src/system/doc.zod.ts

@@ -12,12 +12,13 @@ import { lazySchema } from '../shared/lazy-schema';
  * build time; TS-first stacks may also declare items inline via
  * `defineStack({ docs: [...] })`.
  *
- * Identity model: `name` = filename stem and MUST carry the package
- * namespace prefix (`crm_lead_guide.md` → `crm_lead_guide`). Unlike object
- * names (validated in the kernel because they map to physical table
- * names), doc-name prefixing is a *logical* uniqueness requirement — the
- * metadata registry key carries no package coordinate — so it is enforced
- * by build/publish lint, not by this schema.
+ * Identity model: `name` = filename stem (lowercase snake_case). A namespace
+ * prefix (`crm_lead_guide`) is a *recommended convention*, no longer required:
+ * per ADR-0048, single-doc resolution is package-scoped (`getItem('doc', name,
+ * packageId)` via `?package=` on the detail route), so two packages may ship a
+ * doc with the same bare name and each resolves within its own package — just
+ * like `page`/`dashboard`/`report`. The prefix stays useful for readable,
+ * globally-unique filenames but is not load-bearing for uniqueness.
  *
  * Docs are inert data: the kernel registers them without parsing
  * `content`, and they participate in no runtime behavior. Renderers
@@ -26,13 +27,14 @@ import { lazySchema } from '../shared/lazy-schema';
  */
 export const DocSchema = lazySchema(() => z.object({
   /**
-   * Unique doc name; equals the source filename stem. Namespace-prefixed
-   * (e.g. `crm_lead_guide`) — see ADR-0046 §3.2 for the enforcement
-   * posture (build/publish lint, not kernel rejection).
+   * Doc name; equals the source filename stem. Lowercase snake_case. A
+   * namespace prefix (e.g. `crm_lead_guide`) is recommended for readable,
+   * globally-unique filenames but NOT required — single-doc resolution is
+   * package-scoped (ADR-0048), so bare names are unique within their package.
    */
   name: z.string()
     .regex(/^[a-z][a-z0-9_]*$/, 'name must be lowercase snake_case')
-    .describe('Unique doc name (= filename stem, namespace-prefixed snake_case)'),
+    .describe('Doc name (= filename stem, snake_case; namespace prefix recommended, not required)'),
 
   /**
    * Display title. The CLI derives it from frontmatter `title:` or the