From d28e0e604f9af59f74d864197a1e4efc40edd826 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:56:04 +0800 Subject: [PATCH] fix(spec): repair 25 dead PROTOCOL_MAP links + gate them in CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 (ced379b9e), 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 (142703d54). 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 629a7168e. 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 --- packages/spec/PROTOCOL_MAP.md | 59 +++++++++------------- packages/spec/scripts/protocol-map.test.ts | 53 +++++++++++++++++++ 2 files changed, 78 insertions(+), 34 deletions(-) create mode 100644 packages/spec/scripts/protocol-map.test.ts diff --git a/packages/spec/PROTOCOL_MAP.md b/packages/spec/PROTOCOL_MAP.md index 91d952c0ae..713ddc250c 100644 --- 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 new file mode 100644 index 0000000000..c5cf10e54b --- /dev/null +++ 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); + }); +});