fix(spec): repair 25 dead PROTOCOL_MAP links + gate them in CI

PROTOCOL_MAP.md is hand-written and nothing regenerates it, so renames
orphan rows silently. 25 of its 132 `src/…` links pointed at files that no
longer exist.

The reported row was misdiagnosed, and the git history says why. The prose
"Virtual capabilities for analytics datasets" was NOT a half-finished
rewrite left by #1620 — it has been there verbatim since the map was created
(ced379b), when `data/dataset.zod.ts` held the *seed* schema
(object/externalId/mode/records). It never described that file. So this is
one wrong row plus one absent row, not one half-updated row:

  - `data/dataset.zod.ts` -> `data/seed.zod.ts`, described as seed fixtures
    (renamed by #1620 to free `dataset` for analytics, ADR-0021).
  - the analytics dataset the old prose was reaching for is a real, unlisted
    schema: added as `ui/dataset.zod.ts` (ADR-0021 semantic layer).

The sweep found the same rot everywhere, all from deliberate refactors that
left the map behind:

  - `src/hub/**` (9 rows) — the directory no longer exists (142703d).
    Survivors rehomed: license/registry-config/tenant -> src/system,
    plugin-registry/plugin-security -> src/kernel; composer, marketplace,
    space, hub-federation and api/hub were deleted outright. Section 9 is
    therefore gone and Kernel renumbered 10 -> 9.
  - `src/ai` (10 rows) — narrowed by 629a716. Repointed where a successor
    exists (agent-action -> tool, cost -> usage, rag-pipeline ->
    knowledge-source); dropped nlq/orchestration/predictive/devops-agent/
    feedback-loop/plugin-development/runtime-ops.
  - `identity/role` -> `identity/position` (ADR-0090 D3 renamed sys_role).
  - `security/policy` (#2387), `system/compliance` + `system/masking`
    (ADR-0056 D8) — removed as dead, rows dropped.

Gate: scripts/protocol-map.test.ts asserts every link resolves. Proven to go
red first — it listed exactly the 25 dead links before the fix. It rides Test
Core (required); `core: packages/**` covers the file and turbo's
$TURBO_DEFAULT$ inputs include it, so a map-only edit still re-runs the test
rather than cache-hitting to a false green. A new workflow job would not have
blocked merges (main requires only 4 checks), and check-links.yml is dormant
(workflow_dispatch only) and does not cover packages/spec.

Deliberately asserts links only, not completeness: the map is a curated
digest, not a generated index.

Sibling of #3138, which fixed the identical stale `data/dataset.zod.ts`
pointer in build-skill-references.ts's SKILL_MAP. That one guards generated
artifacts that ship to third parties; PROTOCOL_MAP.md is hand-written and
repo-internal (not in the package's npm `files`), so it needs its own check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

packages/spec/PROTOCOL_MAP.md

@@ -7,6 +7,12 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 > *   **Support Protocols** provide internal structures or auxiliary types.
 > *   Always check the file content for specific Zod schema definitions.
 
+> **Maintaining this file.** It is hand-written and not generated. Every `src/…`
+> link is asserted to resolve by `scripts/protocol-map.test.ts`, so a rename that
+> orphans a row fails CI — repoint the row at the schema that replaced it, or drop
+> the row if the concept is gone. The listing is a *curated digest*, not an
+> exhaustive index: not every schema in `src/` appears here, and that is by design.
+
 ---
 
 ## 🏗️ 1. Data Protocol (`src/data`)
@@ -24,7 +30,8 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`driver-nosql.zod.ts`](src/data/driver-nosql.zod.ts) | | **NoSQL Driver**. Specific configurations for NoSQL drivers. |
 | [`driver/mongo.zod.ts`](src/data/driver/mongo.zod.ts) | | **MongoDB Driver**. MongoDB specific connection options. |
 | [`driver/postgres.zod.ts`](src/data/driver/postgres.zod.ts) | | **PostgreSQL Driver**. PostgreSQL specific connection options. |
-| [`dataset.zod.ts`](src/data/dataset.zod.ts) | | **Dataset**. Virtual capabilities for analytics datasets. |
+| [`seed.zod.ts`](src/data/seed.zod.ts) | | **Seed**. Seed data / fixtures — bootstrap, reference, and demo rows applied on publish. (Was `dataset` until #1620; the `dataset` name now belongs to the analytics semantic layer.) |
+| [`seed-loader.zod.ts`](src/data/seed-loader.zod.ts) | | **Seed Loader**. How seed rows are resolved and applied. |
 | [`analytics.zod.ts`](src/data/analytics.zod.ts) | | **Data Analytics**. Aggregation and multidimensional analysis types. |
 | [`document.zod.ts`](src/data/document.zod.ts) | | **Document**. Unstructured document storage protocol. |
 | [`external-lookup.zod.ts`](src/data/external-lookup.zod.ts) | | **External Lookup**. Virtual lookups to external API data. |
@@ -43,6 +50,7 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`app.zod.ts`](src/ui/app.zod.ts) | ⭐ | **App Container**. Defines the application shell, navigation menu, and branding. |
 | [`view.zod.ts`](src/ui/view.zod.ts) | ⭐ | **Views**. List views (Grid, Kanban) and Record views (Form layouts). |
 | [`page.zod.ts`](src/ui/page.zod.ts) | ⭐ | **Custom Pages**. Drag-and-drop page builder definitions. |
+| [`dataset.zod.ts`](src/ui/dataset.zod.ts) | ⭐ | **Analytics Dataset**. The one semantic layer (ADR-0021): a base object plus declared dimensions and measures. `report` / `dashboard` bind to it by reference instead of declaring their own queries. |
 | [`dashboard.zod.ts`](src/ui/dashboard.zod.ts) | ⭐ | **Dashboards**. Logic for grid-based analytic dashboards. |
 | [`report.zod.ts`](src/ui/report.zod.ts) | ⭐ | **Reports**. Reporting definitions (tabular, summary, matrix). |
 | [`action.zod.ts`](src/ui/action.zod.ts) | ⭐ | **Actions**. Buttons, links, and operations available on UI. |
@@ -74,19 +82,16 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | File | Status | Description |
 | :--- | :--- | :--- |
 | [`agent.zod.ts`](src/ai/agent.zod.ts) | ⭐ | **AI Agent**. Attributes of an AI assistant (role, personality, model). |
-| [`agent-action.zod.ts`](src/ai/agent-action.zod.ts) | ⭐ | **Tools & Actions**. Capabilities exposed to the AI (Function Calling). |
+| [`tool.zod.ts`](src/ai/tool.zod.ts) | ⭐ | **Tools**. Capabilities exposed to the AI (function calling). Was `agent-action`. |
+| [`skill.zod.ts`](src/ai/skill.zod.ts) | ⭐ | **Skills**. Named bundles of instructions plus tools, activated by trigger phrases or conditions. |
 | [`mcp.zod.ts`](src/ai/mcp.zod.ts) | ⭐ | **Model Context Protocol (MCP)**. Standard protocol for connecting AI to tools, resources, and data sources. |
-| [`rag-pipeline.zod.ts`](src/ai/rag-pipeline.zod.ts) | ⭐ | **RAG**. Retrieval Augmented Generation configurations. |
 | [`model-registry.zod.ts`](src/ai/model-registry.zod.ts) | | **LLM Registry**. Configuration for model providers (OpenAI, Anthropic). |
 | [`conversation.zod.ts`](src/ai/conversation.zod.ts) | | **Chat Session**. History and context management for AI chats. |
-| [`nlq.zod.ts`](src/ai/nlq.zod.ts) | | **Natural Language Query**. Definitions for text-to-SQL/Query logic. |
-| [`orchestration.zod.ts`](src/ai/orchestration.zod.ts) | | **Orchestration**. Multi-agent coordination patterns. |
-| [`feedback-loop.zod.ts`](src/ai/feedback-loop.zod.ts) | | **RLHF**. Feedback mechanisms for model improvement. |
-| [`cost.zod.ts`](src/ai/cost.zod.ts) | | **Cost Tracking**. Token usage and billing metrics. |
-| [`devops-agent.zod.ts`](src/ai/devops-agent.zod.ts) | | **DevOps Agent**. Specialized agent for system operations. |
-| [`plugin-development.zod.ts`](src/ai/plugin-development.zod.ts) | | **Plugin Dev**. AI assistance for plugin creation. |
-| [`predictive.zod.ts`](src/ai/predictive.zod.ts) | | **Predictive AI**. Machine learning model configurations. |
-| [`runtime-ops.zod.ts`](src/ai/runtime-ops.zod.ts) | | **Runtime Ops**. Operational parameters for AI runtime. |
+| [`knowledge-source.zod.ts`](src/ai/knowledge-source.zod.ts) | | **Knowledge Source**. What to index and which adapter to use (the RAG retrieval binding). |
+| [`knowledge-document.zod.ts`](src/ai/knowledge-document.zod.ts) | | **Knowledge Document**. Document / chunk / hit shapes shared by every knowledge adapter. |
+| [`embedding.zod.ts`](src/ai/embedding.zod.ts) | | **Embeddings**. Embedding model and vector store configuration. |
+| [`solution-blueprint.zod.ts`](src/ai/solution-blueprint.zod.ts) | | **Solution Blueprint**. Plan-first authoring target for high-level goals (ADR-0033). |
+| [`usage.zod.ts`](src/ai/usage.zod.ts) | | **Usage**. Token consumption measurement. Was `cost`. |
 
 ---
 
@@ -98,9 +103,9 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`identity.zod.ts`](src/identity/identity.zod.ts) | ⭐ | **User Identity**. User accounts, authentication attributes. |
 | [`organization.zod.ts`](src/identity/organization.zod.ts) | ⭐ | **Organization**. Multi-tenancy structure (spaces, companies). |
 | [`permission.zod.ts`](src/security/permission.zod.ts) | ⭐ | **Permissions**. ACLs for Objects, Fields, and Apps. |
-| [`role.zod.ts`](src/identity/role.zod.ts) | | **Roles**. Hierarchical role definitions. |
-| [`policy.zod.ts`](src/security/policy.zod.ts) | | **Security Policy**. Global security settings and restrictions. |
+| [`position.zod.ts`](src/identity/position.zod.ts) | | **Positions**. The assignable bundle of permission sets a user holds. Renamed from `role` by ADR-0090 (`sys_role`→`sys_position`); `profile` was removed in the same wave. |
 | [`sharing.zod.ts`](src/security/sharing.zod.ts) | | **Sharing Rules**. Record-level access rules (sharing calculation). |
+| [`explain.zod.ts`](src/security/explain.zod.ts) | | **Access Explain**. Why a principal can or cannot reach a record. |
 | [`rls.zod.ts`](src/security/rls.zod.ts) | | **Row Level Security**. Database-level RLS definitions. |
 | [`territory.zod.ts`](src/security/territory.zod.ts) | | **Territory Management**. Sales territory models. |
 | [`scim.zod.ts`](src/identity/scim.zod.ts) | | **SCIM Protocol**. Identity provisioning standards. |
@@ -141,10 +146,11 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`notification.zod.ts`](src/system/notification.zod.ts) | | **Notifications**. System-wide notification preferences. |
 | [`translation.zod.ts`](src/system/translation.zod.ts) | | **i18n**. Internationalization and localization. |
 | [`worker.zod.ts`](src/system/worker.zod.ts) | | **Worker Nodes**. Background worker scaling config. |
-| [`compliance.zod.ts`](src/system/compliance.zod.ts) | | **Compliance**. GDPR/SOC2 policies. |
 | [`encryption.zod.ts`](src/system/encryption.zod.ts) | | **Encryption**. At-rest and in-transit encryption keys. |
-| [`masking.zod.ts`](src/system/masking.zod.ts) | | **Data Masking**. PII data masking rules. |
 | [`migration.zod.ts`](src/system/migration.zod.ts) | | **Migration**. Database schema migration tracking. |
+| [`license.zod.ts`](src/system/license.zod.ts) | | **Licensing**. License keys and entitlements. |
+| [`registry-config.zod.ts`](src/system/registry-config.zod.ts) | | **Registry Config**. Configuration for the package registry. |
+| [`tenant.zod.ts`](src/system/tenant.zod.ts) | | **Tenant**. Multi-tenant environment isolation. |
 | [`change-management.zod.ts`](src/system/change-management.zod.ts) | | **Change Mgmt**. Deployment history and rollbacks. |
 | [`collaboration.zod.ts`](src/system/collaboration.zod.ts) | | **Collaboration**. Real-time collaboration settings. |
 
@@ -174,29 +180,12 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`batch.zod.ts`](src/api/batch.zod.ts) | | **Batch API**. Bulk request processing. |
 | [`contract.zod.ts`](src/api/contract.zod.ts) | | **API Contracts**. Versioned API signatures. |
 | [`storage.zod.ts`](src/api/storage.zod.ts) | | **Storage API**. File upload/download endpoints. |
-| [`hub.zod.ts`](src/api/hub.zod.ts) | | **Hub API**. Main Hub communication protocol. |
 | [`registry.zod.ts`](src/api/registry.zod.ts) | | **Registry API**. Package registry interface. |
+| [`package-api.zod.ts`](src/api/package-api.zod.ts) | | **Package API**. Package lifecycle endpoints (`/api/v1/packages`). |
 
 ---
 
-## 🧩 9. Hub & Ecosystem (`src/hub`)
-*The "Marketplace as Code" layer. Defines the package ecosystem.*
-
-| File | Status | Description |
-| :--- | :--- | :--- |
-| [`registry-config.zod.ts`](src/hub/registry-config.zod.ts) | ⭐ | **Registry Config**. Configuration for the package registry. |
-| [`plugin-registry.zod.ts`](src/hub/plugin-registry.zod.ts) | | **Plugin Registry**. Metadata for available plugins. |
-| [`marketplace.zod.ts`](src/hub/marketplace.zod.ts) | | **Marketplace**. Listings, pricing, and vendor info. |
-| [`tenant.zod.ts`](src/hub/tenant.zod.ts) | | **Tenant**. Multi-tenant environment isolation. |
-| [`license.zod.ts`](src/hub/license.zod.ts) | | **Licensing**. License keys and entitlements. |
-| [`composer.zod.ts`](src/hub/composer.zod.ts) | | **Composer**. Package dependency resolution. |
-| [`space.zod.ts`](src/hub/space.zod.ts) | | **Space**. Collaborative workspaces. |
-| [`hub-federation.zod.ts`](src/hub/hub-federation.zod.ts) | | **Federation**. Cross-instance hub communication. |
-| [`plugin-security.zod.ts`](src/hub/plugin-security.zod.ts) | | **Plugin Security**. Security verification for plugins. |
-
----
-
-## ⚙️ 10. Kernel & Runtime (`src/kernel`)
+## ⚙️ 9. Kernel & Runtime (`src/kernel`)
 *The "OS as Code" layer. Defines low-level plugin lifecycles.*
 
 | File | Status | Description |
@@ -210,6 +199,8 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`metadata-loader.zod.ts`](src/kernel/metadata-loader.zod.ts) | | **Loader**. Logic for loading definitions from disk/DB. |
 | [`plugin-loading.zod.ts`](src/kernel/plugin-loading.zod.ts) | ⭐ | **Plugin Loading**. Loading strategies, production-safe hot reload (`environment`, `productionSafety`), full plugin sandboxing (`scope`, `ipc`), code splitting, caching, and performance monitoring. |
 | [`plugin-runtime.zod.ts`](src/kernel/plugin-runtime.zod.ts) | ⭐ | **Dynamic Loading**. Runtime load/unload of plugins (`DynamicLoadRequest`, `DynamicUnloadRequest`), activation events, plugin discovery from registries/directories, and source resolution (npm/local/url/registry/git). |
+| [`plugin-registry.zod.ts`](src/kernel/plugin-registry.zod.ts) | | **Plugin Registry**. Metadata for available plugins. |
+| [`plugin-security.zod.ts`](src/kernel/plugin-security.zod.ts) | | **Plugin Security**. Security verification for plugins. |
 | [`plugin-versioning.zod.ts`](src/kernel/plugin-versioning.zod.ts) | | **Versioning**. Semantic versioning rules for plugins. |
 | [`plugin-validator.zod.ts`](src/kernel/plugin-validator.zod.ts) | | **Validation**. Integrity checks for plugins. |
 | [`plugin-structure.zod.ts`](src/kernel/plugin-structure.zod.ts) | | **Structure**. Zod rules for folder layout and file naming. |

packages/spec/scripts/protocol-map.test.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * PROTOCOL_MAP.md is hand-written and repo-internal (it is not in the package's
+ * npm `files` list, so it never ships). Nothing regenerates it, which means a
+ * rename that moves a `*.zod.ts` leaves its row pointing at a file that no
+ * longer exists and no build step notices.
+ *
+ * That is not hypothetical: the Dataset→Seed rename (#1620, ADR-0021) left
+ * `src/data/dataset.zod.ts` dangling here, and by the time this gate was added
+ * 25 of the 132 links were dead — an entire section (`src/hub`) had been
+ * deleted wholesale. This asserts every link resolves; it deliberately does NOT
+ * assert the reverse (that every schema is listed), since the map is a curated
+ * digest, not a generated index.
+ *
+ * Sibling gate: #3138 covers the same #1620 fallout on the *generated* side —
+ * `build-skill-references.ts`'s SKILL_MAP held the identical stale
+ * `data/dataset.zod.ts` pointer. That one is a regenerate-and-diff check on
+ * artifacts that ship to third parties, so it runs as `check:skill-refs` in
+ * lint.yml. This file is hand-written and never generated, so a plain assertion
+ * is the whole job; it rides Test Core, whose `packages/**` filter has no
+ * blind spot for spec changes.
+ */
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const mapPath = resolve(packageRoot, 'PROTOCOL_MAP.md');
+
+/** Matches the `](src/...)` target of every markdown link in the tables. */
+const LINK_RE = /\]\((src\/[^)]+)\)/g;
+
+function protocolMapLinks(): string[] {
+  const md = readFileSync(mapPath, 'utf8');
+  return [...md.matchAll(LINK_RE)].map((m) => m[1]);
+}
+
+describe('PROTOCOL_MAP.md', () => {
+  it('links only to files that exist', () => {
+    const dead = protocolMapLinks().filter((link) => !existsSync(resolve(packageRoot, link)));
+
+    expect(dead, `PROTOCOL_MAP.md links to ${dead.length} file(s) that do not exist:\n` +
+      dead.map((d) => `  - ${d}`).join('\n') +
+      '\n\nRepoint the row at the schema that replaced it, or drop the row if the concept is gone.').toEqual([]);
+  });
+
+  it('actually finds links to check (guards against the regex silently matching nothing)', () => {
+    expect(protocolMapLinks().length).toBeGreaterThan(100);
+  });
+});