feat(book): documentation navigation spine + derived membership (ADR-0046 §6, P3a/P3b) (#1879)

xuyushun441-sys · os-zhuang · claude · web-flow · commit 71578f2b3168 · 2026-06-15T14:27:48.000+08:00
* docs(adr-0046): P3 increment — `book` navigation as a spine with derived membership

Adds §6 to ADR-0046 specifying the P3 navigation model. A `book` is a metadata
element that stores only an ordered spine (groups); membership is derived by
rule (`include` glob/tag) plus optional per-doc `order`/`group`, never a central
array. This is chosen so AI authoring stays create-and-forget (no central-array
read-modify-write, §6.2.1) and runtime overlay stays merge-safe under RFC 7396.

Also specified: the implicit per-package book (packageId), `audience` access
(org / public≡guest / {profile}) enforced at the read layer, and a host-based
anonymous "library" portal reusing apps/docs (Fumadocs + per-host ISR) rather
than greenfield SSR. No `meta.json`: `book` is metadata, authored as *.book.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* feat(spec): add `book` navigation element — spine + derived-membership resolver (ADR-0046 §6, P3a)

- BookSchema (spine: ordered groups + audience + identity), BookGroupSchema,
  BookNodeSchema, defineBook(); additive scalar `doc.order` / `doc.group`.
- resolveBookTree(): pure derived-membership resolver — the AI-safety core. A
  doc joins a group by `include` glob/tag or explicit `doc.group`; explicit
  `pages` override (verbatim order, `---`, `...` rest, missing-doc, object
  nodes); unmatched docs → synthetic Uncategorized; first-group-wins dedup;
  package-scoped includes.
- deriveImplicitPackageBook(): the implicit per-package book (no "flat" fork).
- Register `book` metadata type (allowOrgOverride:true, loadOrder 99); artifact
  field `books` → `book`; `stack.books`.
- 15 resolver/schema tests; spec tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* feat(book): REST resolved-tree endpoint + audience gating + runtime wiring (ADR-0046 §6, P3b)

- REST `GET /meta/book/:name/tree` resolves a book spine against the docs that
  exist now into a rendered tree (resolveBookTree); unknown name → implicit
  per-package book. Read-layer `audience` gating: anonymous callers get a book
  only when its audience is `public` (else 401), enforced in the read path —
  not just the UI — since /meta reads are anonymous-reachable.
- Register `book` across the runtime metadata enumerations that were missing it:
  PLURAL_TO_SINGULAR (`books`→`book`), engine.registerApp metadataArrayKeys,
  app-plugin app-category keys, and the builtin type-schema map (book→BookSchema
  for Studio editing / diagnostics). Export `defineBook` from the spec root.
- Showcase ships a real `showcase_manual` book (audience: public) demonstrating
  explicit `pages` + `...` rest (start) and a derived `include` rule (guides).

Verified live (artifact boot): GET /meta/book → 1 item; /tree returns the
derived tree (guides filled by rule, other-package docs → Uncategorized);
public book serves anonymously (200), implicit org book is gated (401).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* chore: changeset for book navigation (ADR-0046 §6)

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/book-navigation-spine.md b/.changeset/book-navigation-spine.md
@@ -0,0 +1,14 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/rest": minor
+"@objectstack/runtime": patch
+---
+
+feat(book): documentation navigation as a `book` element — spine + derived membership (ADR-0046 §6)
+
+Adds the `book` metadata element: a navigation **spine** (ordered groups + `audience` + identity) whose membership is **derived** by rule (`include` glob/tag) plus optional per-doc `order`/`group`, never a central array. This keeps AI authoring create-and-forget (no central-array read-modify-write) and runtime overlay merge-safe (RFC 7396 treats arrays atomically).
+
+- `BookSchema` + `resolveBookTree()` derived-membership resolver + `defineBook()` + additive `doc.order`/`doc.group`.
+- Register `book` as a render-time metadata type (`allowOrgOverride: true`); wire it through the runtime type enumerations (PLURAL_TO_SINGULAR, engine registration, artifact field map, type-schema map).
+- REST `GET /meta/book/:name/tree` resolves the tree; read-layer `audience` gating (`public` ≡ anonymous; `org`/`{profile}` require sign-in).
diff --git a/.claude/launch.json b/.claude/launch.json
diff --git a/examples/app-showcase/objectstack.config.ts b/examples/app-showcase/objectstack.config.ts
@@ -24,6 +24,7 @@ import { allWebhooks } from './src/webhooks/index.js';
 import { allJobs } from './src/jobs/index.js';
 import { allEmails } from './src/emails/index.js';
 import { ShowcaseAssistantAgent, ProjectOpsSkill } from './src/agents/index.js';
+import { allBooks } from './src/books/index.js';
 import {
   allRoles,
   allPermissionSets,
@@ -143,6 +144,7 @@ export default defineStack({
   views: [TaskViews, ProjectViews],
   pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage],
   dashboards: [ChartGalleryDashboard],
+  books: allBooks,
   datasets: [ShowcaseTaskDataset, ShowcaseProjectDataset],
   reports: allReports,
   actions: allActions,
diff --git a/examples/app-showcase/src/books/index.ts b/examples/app-showcase/src/books/index.ts
@@ -0,0 +1,36 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineBook } from '@objectstack/spec';
+
+/**
+ * Showcase documentation book (ADR-0046 §6). A spine only: groups are ordered
+ * and curated, but membership is DERIVED — `guides` picks up any
+ * `showcase_*_guide` doc by rule, so a new guide files itself with no edit to
+ * this book. `audience: 'public'` exposes it anonymously via the library
+ * portal so the resolved tree can be verified without a session.
+ */
+export const ShowcaseBook = defineBook({
+  name: 'showcase_manual',
+  label: 'Showcase Manual',
+  description: 'Everything in the kitchen-sink workspace.',
+  slug: 'manual',
+  order: 0,
+  audience: 'public',
+  groups: [
+    {
+      key: 'start',
+      label: 'Getting Started',
+      order: 1,
+      // Explicit override: pin the index first, then sweep any other intro docs.
+      pages: ['showcase_index', '...'],
+    },
+    {
+      key: 'guides',
+      label: 'Guides',
+      order: 2,
+      include: 'showcase_*_guide', // derived: every guide doc, present and future
+    },
+  ],
+});
+
+export const allBooks = [ShowcaseBook];
diff --git a/packages/metadata/src/plugin.ts b/packages/metadata/src/plugin.ts
@@ -72,6 +72,7 @@ const ARTIFACT_FIELD_TO_TYPE: Record<string, string> = {
     connectors: 'connector',
     emailTemplates: 'email_template',
     docs: 'doc',
+    books: 'book',
     data: 'dataset',
 };
 
diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts
@@ -938,6 +938,8 @@ export class ObjectQL implements IDataEngine {
         'connectors',
         // System Protocol — package documentation (ADR-0046); inert data
         'docs',
+        // Documentation navigation spine (ADR-0046 §6)
+        'books',
       ];
       for (const key of metadataArrayKeys) {
           const items = (manifest as any)[key];
@@ -1083,7 +1085,7 @@ export class ObjectQL implements IDataEngine {
           'roles', 'permissions', 'profiles', 'sharingRules', 'policies',
           'agents', 'ragPipelines', 'apis',
           'hooks', 'mappings', 'analyticsCubes', 'connectors',
-          'docs',
+          'docs', 'books',
       ];
       for (const key of metadataArrayKeys) {
           const items = (plugin as any)[key];
diff --git a/packages/rest/src/rest-server.ts b/packages/rest/src/rest-server.ts
@@ -1922,6 +1922,74 @@ export class RestServer {
                 },
             });
 
+            // ADR-0046 §6 — GET /meta/book/:name/tree
+            // Resolve a book spine against the docs that exist *now* into a
+            // rendered tree (membership is DERIVED, never stored — §6.2.1). An
+            // unknown name is treated as a package id and resolved against the
+            // implicit per-package book (§6.4). Anonymous requests only see a
+            // book whose `audience` is `public` (§6.7 read-layer gating).
+            this.routeManager.register({
+                method: 'GET',
+                path: `${metaPath}/book/:name/tree`,
+                handler: async (req: any, res: any) => {
+                    try {
+                        const environmentId = isScoped ? req.params?.environmentId : undefined;
+                        const prot = await this.resolveProtocol(environmentId, req);
+                        const locale = this.extractLocale(req);
+                        const packageId = req.query?.package || undefined;
+                        const { resolveBookTree, deriveImplicitPackageBook, isPublicAudience, resolveDocLocale } =
+                            await import('@objectstack/spec/system');
+
+                        const norm = (raw: any): any[] =>
+                            Array.isArray(raw) ? raw : (raw && Array.isArray(raw.items) ? raw.items : []);
+
+                        const books = norm(await prot.getMetaItems({
+                            type: 'book',
+                            ...(packageId ? { packageId } : {}),
+                            ...(environmentId ? { environmentId } : {}),
+                        } as any));
+                        let book = books.find((b: any) => b && b.name === req.params.name);
+                        if (!book) {
+                            // Unknown name → the implicit per-package book (§6.4).
+                            book = deriveImplicitPackageBook(req.params.name, req.params.name);
+                        }
+
+                        // §6.7 — anonymous callers only get `public` books.
+                        const ctx = await this.resolveExecCtx(environmentId, req).catch(() => undefined);
+                        if (!ctx?.userId && !isPublicAudience((book as any).audience)) {
+                            sendError(res, { code: 'unauthorized', message: 'This documentation requires sign-in', status: 401 });
+                            return;
+                        }
+
+                        const docs = norm(await prot.getMetaItems({
+                            type: 'doc',
+                            ...(packageId ? { packageId } : {}),
+                            ...(environmentId ? { environmentId } : {}),
+                        } as any))
+                            .map((d: any) => (d && typeof d === 'object' ? resolveDocLocale(d, locale) : d))
+                            .map((d: any) => ({
+                                name: d.name,
+                                label: d.label,
+                                description: d.description,
+                                order: d.order,
+                                group: d.group,
+                                tags: d.tags,
+                                packageId: d._packageId,
+                            }));
+
+                        const tree = resolveBookTree(book as any, docs, (book as any)._packageId);
+                        res.json(tree);
+                    } catch (error: any) {
+                        logError("[REST] Unhandled error:", error);
+                        sendError(res, error);
+                    }
+                },
+                metadata: {
+                    summary: 'Resolve a documentation book spine into its rendered tree (ADR-0046 §6)',
+                    tags: ['metadata'],
+                },
+            });
+
             this.routeManager.register({
                 method: 'GET',
                 path: `${metaPath}/:type/:name`,
diff --git a/packages/runtime/src/app-plugin.ts b/packages/runtime/src/app-plugin.ts
@@ -69,7 +69,7 @@ export class AppPlugin implements Plugin {
                 'flows', 'workflows', 'triggers', 'agents', 'tools', 'skills',
                 'actions', 'permissions', 'roles', 'profiles', 'translations',
                 'sharingRules', 'ragPipelines', 'data', 'emailTemplates',
-                'docs',
+                'docs', 'books',
             ];
             const hasAppPayload = APP_CATEGORY_KEYS.some((k) => {
                 const v = (bundle && bundle[k]) ?? (sys && sys[k]);
diff --git a/packages/spec/src/index.ts b/packages/spec/src/index.ts
@@ -76,6 +76,7 @@ export type { ExpandedViewItem } from './ui/view.zod';
 export { defineApp } from './ui/app.zod';
 export { defineFlow } from './automation/flow.zod';
 export { defineJob } from './system/job.zod';
+export { defineBook } from './system/book.zod';
 export { defineAgent } from './ai/agent.zod';
 export { defineTool } from './ai/tool.zod';
 export { defineSkill } from './ai/skill.zod';
diff --git a/packages/spec/src/kernel/metadata-plugin.zod.ts b/packages/spec/src/kernel/metadata-plugin.zod.ts
@@ -105,6 +105,7 @@ export const MetadataTypeSchema = lazySchema(() => z.enum([
   'service',     // Service definitions
   'email_template', // Outbound email templates (EmailTemplateSchema)
   'doc',         // Package documentation — flat Markdown items (DocSchema, ADR-0046)
+  'book',        // Documentation navigation spine (BookSchema, ADR-0046 §6)
 
   // Security Protocol
   'permission',  // Permission sets (PermissionSetSchema)
@@ -666,6 +667,10 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntry[] = [
   // (ADR-0033). Collected from flat `src/docs/*.md` by the CLI; the kernel
   // never parses `content`. loadOrder is last: nothing references docs.
   { type: 'doc', label: 'Documentation', description: 'Package documentation — flat Markdown items (ADR-0046)', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
+  // Navigation spine over docs (ADR-0046 §6): ordered groups, membership derived
+  // by rule. Render-time like view/dashboard ⇒ overlay-allowed so Studio can
+  // drag-edit; runtime-creatable for AI/authors. loadOrder last (references docs).
+  { type: 'book', label: 'Documentation Book', description: 'Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
 
   // Security Protocol
   { type: 'permission', label: 'Permission Set', filePatterns: ['**/*.permission.ts', '**/*.permission.yml'], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: false, loadOrder: 15, domain: 'security' },
diff --git a/packages/spec/src/kernel/metadata-type-schemas.ts b/packages/spec/src/kernel/metadata-type-schemas.ts
@@ -49,6 +49,7 @@ import { JobSchema } from '../system/job.zod';
 import { EmailTemplateDefinitionSchema } from '../system/email-template.zod';
 import { AppTranslationBundleSchema } from '../system/translation.zod';
 import { DocSchema } from '../system/doc.zod';
+import { BookSchema } from '../system/book.zod';
 
 import { PermissionSetSchema } from '../security/permission.zod';
 import { RoleSchema } from '../identity/role.zod';
@@ -97,6 +98,7 @@ const BUILTIN_METADATA_TYPE_SCHEMAS: Partial<Record<MetadataType, z.ZodType>> =
   translation: AppTranslationBundleSchema,
   email_template: EmailTemplateDefinitionSchema,
   doc: DocSchema, // ADR-0046: flat Markdown package documentation
+  book: BookSchema as unknown as z.ZodType, // ADR-0046 §6: documentation navigation spine
   // `router` / `function` / `service` are code-only (allowRuntimeCreate: false).
 
   // Security Protocol
diff --git a/packages/spec/src/shared/metadata-collection.zod.ts b/packages/spec/src/shared/metadata-collection.zod.ts
@@ -136,6 +136,7 @@ export const PLURAL_TO_SINGULAR: Record<string, string> = {
   views: 'view',
   emailTemplates: 'email_template',
   docs: 'doc',
+  books: 'book',
 };
 
 /** Reverse mapping: singular metadata type → plural manifest field name. */
diff --git a/packages/spec/src/stack.zod.ts b/packages/spec/src/stack.zod.ts
@@ -53,6 +53,7 @@ import { WebhookSchema } from './automation/webhook.zod';
 // System Protocol (additional)
 import { EmailTemplateDefinitionSchema } from './system/email-template.zod';
 import { DocSchema } from './system/doc.zod';
+import { BookSchema } from './system/book.zod';
 
 // Integration Protocol
 import { ConnectorSchema } from './integration/connector.zod';
@@ -226,6 +227,7 @@ export const ObjectStackDefinitionSchema = lazySchema(() => z.object({
   jobs: z.array(JobSchema).optional().describe('Background / Scheduled Jobs (run by IJobService on cron/interval/once schedules)'),
   emailTemplates: z.array(EmailTemplateDefinitionSchema).optional().describe('Email Templates resolved by IEmailService.sendTemplate({ template, locale })'),
   docs: z.array(DocSchema).optional().describe('Package documentation — flat Markdown items compiled from src/docs/*.md (ADR-0046)'),
+  books: z.array(BookSchema).optional().describe('Documentation navigation spines — ordered groups with derived membership (ADR-0046 §6)'),
 
   /**
    * ObjectGuard: Security Layer
diff --git a/packages/spec/src/system/book.test.ts b/packages/spec/src/system/book.test.ts
diff --git a/packages/spec/src/system/book.zod.ts b/packages/spec/src/system/book.zod.ts
diff --git a/packages/spec/src/system/doc.zod.ts b/packages/spec/src/system/doc.zod.ts
diff --git a/packages/spec/src/system/index.ts b/packages/spec/src/system/index.ts
