objectstack-ai · os-zhuang · Jul 17, 2026 · Jul 17, 2026
diff --git a/packages/spec/PROTOCOL_MAP.md b/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. |

diff --git a/packages/spec/scripts/protocol-map.test.ts b/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);
+  });
+});