@@ -0,0 +1,59 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': patch
+'@objectstack/runtime': patch
+---
+
+feat(spec): one declaration per version grammar — eight regex carriers of "the version of a package or plugin" now reference three exported constants
+
+Clause-②: yes (widening)
+
+**No accept set moves, and that is the whole point of this change.** Eight sites
+spelled a version regex out as a literal of their own. Five of those spellings
+were byte-identical to each other, two more were byte-identical to each other,
+and the eighth stood alone — three accept sets written eight times, growing on
+their own: three of the eight were published schema declarations with no parse
+caller at all, added by authors who copied a neighbour's literal. Each site now
+references the constant carrying the pattern it already enforced, byte for byte.
+A ninth in-repo carrier of the same concept spelled no regex at all:
+`PackageManifestSchema.version` is a bare `z.string()`, and it stays one here.
+
+`@objectstack/spec/kernel` gains three exported patterns:
+
+- `MAJOR_MINOR_PATCH_VERSION_PATTERN` — three numeric segments and nothing
+  else. Referenced by `ManifestSchema.version`,
+  `MetadataPluginManifestSchema.version`, `PluginRegistryEntrySchema.version`,
+  `PluginMetadataSchema.version`, and the `PATCH /api/v1/packages/:id` door in
+  `@objectstack/runtime`.
+- `SEMVER_SHAPED_VERSION_PATTERN` — `major.minor.patch` with an optional
+  `-prerelease` and an optional `+build` suffix, identifiers in either ASCII
+  case. Referenced by `PluginSchema.version` and by
+  `PluginLoader.isSemverShapedVersion` in `@objectstack/core`. Those two
+  converged on one spelling under the widen-never-narrow ruling and were held
+  equal by hand until now; they reference one declaration and can no longer
+  drift apart.
+- `SEMVER_SHAPED_LOWERCASE_VERSION_PATTERN` — the same with the suffix
+  identifiers restricted to lowercase ASCII. Referenced by
+  `PackageVersionSchema.version`.
+
+⛔ **The three are not interchangeable** — they are three different accept sets,
+and referencing the wrong one moves a published accept set. None of the three is
+a SemVer 2.0.0 conformance check and none is named as one: two accept forms
+SemVer forbids (leading zeroes in the numeric core, empty and leading-zero
+identifiers), one refuses forms it requires. For ordering or precedence,
+`dependency-resolver.ts` in `@objectstack/core` is still the module to extend.
+
+**Nothing an author can write changes.** Every regex is byte-identical to the
+literal it replaces — verified per carrier by sha256 over the extracted literal
+— and every existing suite passes unedited. Those two together are the
+neutrality proof, and they are the whole of it. `PackageManifestSchema.version`
+keeps its bare `z.string()`; it is deliberately untouched here. No `.describe()`
+text, refusal message or JSON Schema `pattern` moves. Regenerating the spec's
+artifacts moved `api-surface/kernel.json` and `export-origins/kernel.json` and
+nothing else, each gaining the three constant names — ⛔ read that as a check
+that nothing unexpected regenerated, never as evidence about the accept set: the
+artifacts that stayed byte-unchanged do not record a `.regex()` pattern in the
+first place. A new pin,
+`src/kernel/version-grammar.test.ts`, records each grammar's verdict on twelve
+witness strings so the next deliberate move to any of them is one visible edit
+to one matrix.
@@ -5,6 +5,7 @@ import type { Logger } from '@objectstack/spec/contracts';
 import { parseSignature } from './security/plugin-artifact-signature.js';
 import { serviceNotRegisteredError } from './service-not-registered.js';
 import { assertPluginContract } from './plugin-contract.js';
+import { SEMVER_SHAPED_VERSION_PATTERN } from '@objectstack/spec/kernel';
 
 /**
  * Service Lifecycle Types
@@ -484,22 +485,24 @@ export class PluginLoader {
      * `/^\d+\.\d+\.\d+$/` admitted it too, because `\d+` always has — and
      * #16365's ruling (widen, never narrow: nothing that loads today stops
      * loading) froze the accept set. So #17070 moved the CLAIM instead of the
-     * grammar: the regex below is byte-for-byte what it has been, and this
+     * grammar: the grammar below is byte-for-byte what it has been, and this
      * method's name and this docblock are what changed.
      *
      * ⚠️ Need real SemVer 2.0.0 conformance — ordering, precedence, or a
      * standards-compliant verdict? This is not that predicate; do not reach for
      * it. `dependency-resolver.ts` parses and COMPARES versions and is the
      * module to extend.
      *
-     * ⭐ This regex is `PluginSchema.version`'s spelling character for character
-     * (`@objectstack/spec`, `kernel/plugin.zod.ts`) — the convergence #16365
-     * created, and a property `plugin-loader.test.ts` asserts rather than
-     * narrates. Change one spelling and you must change both.
+     * ⭐ This predicate and `PluginSchema.version` (`@objectstack/spec`,
+     * `kernel/plugin.zod.ts`) reference ONE declaration — the exported
+     * `SEMVER_SHAPED_VERSION_PATTERN` (`@objectstack/spec/kernel`) — so the
+     * convergence #16365 created can no longer be undone by editing one side.
+     * Each used to spell the grammar out and the two were held equal character
+     * for character by hand; `plugin-loader.test.ts` asserts the resulting
+     * accept set rather than narrating it.
      */
     private isSemverShapedVersion(version: string): boolean {
-        const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/;
-        return semverRegex.test(version);
+        return SEMVER_SHAPED_VERSION_PATTERN.test(version);
     }
 
     private async verifyPluginSignature(plugin: PluginMetadata): Promise<void> {
 
@@ -75,19 +75,21 @@ import { stripReadDecorations } from '@objectstack/spec/kernel';
 // REFERENCE at the install door below. `ManifestSchema.shape.version` and
 // `ManifestSchema.shape.id` are the very field schemas
 // `PackageInstallRequestSchema` binds through `manifest: ManifestSchema` — not
-// copies of them. ⛔ A hand-written semver regex here would be the THIRD
-// judgment of that one key on this one surface (the `PATCH /packages/:id` door
-// further down already keeps its own copy), and the version-grammar canon is an
-// open question on its own card: asking the declaration means whatever that
-// canon decides reaches this door with no edit to this file. The same holds for
-// the id — `MANIFEST_ID_PATTERN` is declared ONCE in `kernel/manifest.zod.ts`
-// and shared with `PackageSchema.manifestId`, so ⛔ no reverse-domain regex is
-// spelled here either.
+// copies of them. ⛔ A hand-written semver regex here would be a SECOND grammar
+// for the version key on this one surface: the `PATCH /packages/:id` door
+// further down judges the same key and keeps no copy of its own either — it
+// references `MAJOR_MINOR_PATCH_VERSION_PATTERN`, the same constant
+// `ManifestSchema`'s own `version` field references (`@objectstack/spec`
+// `kernel/version-grammar.ts`). Both doors therefore read ONE declaration, and
+// a change to that declaration reaches both of them with no edit to this file.
+// The same holds for the id — `MANIFEST_ID_PATTERN` is declared ONCE in
+// `kernel/manifest.zod.ts` and shared with `PackageSchema.manifestId`, so ⛔ no
+// reverse-domain regex is spelled here either.
 //
 // `manifestIdRefusal` is imported for exactly one limb: the fallback when a
 // failed parse somehow carries no issue. Even that limb then prints the
 // DECLARATION's own sentence rather than a second one invented here.
-import { ManifestSchema, manifestIdRefusal } from '@objectstack/spec/kernel';
+import { ManifestSchema, MAJOR_MINOR_PATCH_VERSION_PATTERN, manifestIdRefusal } from '@objectstack/spec/kernel';
 // [#17672] The repo's ONE message for a single-valued query parameter supplied
 // more than once, from the module whose header is the authority on the rule
 // (`packages/rest/src/query-multiplicity.ts`). Imported, never restated: this
@@ -1765,7 +1767,7 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin
             if (patch.name !== undefined && patch.name === '') {
                 return { handled: true, response: deps.error('name must not be empty', 400) };
             }
-            if (patch.version !== undefined && !/^\d+\.\d+\.\d+$/.test(patch.version)) {
+            if (patch.version !== undefined && !MAJOR_MINOR_PATCH_VERSION_PATTERN.test(patch.version)) {
                 return { handled: true, response: deps.error('version must be semantic (e.g. 1.0.0)', 400) };
             }
             if (patch.name === undefined && patch.description === undefined && patch.version === undefined) {
 
@@ -154,6 +154,7 @@
     "ListPackagesResponse (type)",
     "ListPackagesResponseParsed (type)",
     "ListPackagesResponseSchema (const)",
+    "MAJOR_MINOR_PATCH_VERSION_PATTERN (const)",
     "MANIFEST_ID_EXAMPLES (const)",
     "MANIFEST_ID_PATTERN (const)",
     "METADATA_READ_DECORATIONS (const)",
@@ -377,6 +378,8 @@
     "SBOMParsed (type)",
     "SBOMSchema (const)",
     "SEED_WRITE_EXECUTION_CONTEXT (const)",
+    "SEMVER_SHAPED_LOWERCASE_VERSION_PATTERN (const)",
+    "SEMVER_SHAPED_VERSION_PATTERN (const)",
     "SandboxConfig (type)",
     "SandboxConfigParsed (type)",
     "SandboxConfigSchema (const)",
 
@@ -153,6 +153,7 @@
     "ListPackagesResponse": "src/kernel/package-registry.zod.ts#ListPackagesResponse (type)",
     "ListPackagesResponseParsed": "src/kernel/package-registry.zod.ts#ListPackagesResponseParsed (type)",
     "ListPackagesResponseSchema": "src/kernel/package-registry.zod.ts#ListPackagesResponseSchema (const)",
+    "MAJOR_MINOR_PATCH_VERSION_PATTERN": "src/kernel/version-grammar.ts#MAJOR_MINOR_PATCH_VERSION_PATTERN (const)",
     "MANIFEST_ID_EXAMPLES": "src/kernel/manifest.zod.ts#MANIFEST_ID_EXAMPLES (const)",
     "MANIFEST_ID_PATTERN": "src/kernel/manifest.zod.ts#MANIFEST_ID_PATTERN (const)",
     "METADATA_READ_DECORATIONS": "src/kernel/metadata-read-decorations.ts#METADATA_READ_DECORATIONS (const)",
@@ -375,6 +376,8 @@
     "SBOMParsed": "src/kernel/plugin-security.zod.ts#SBOMParsed (type)",
     "SBOMSchema": "src/kernel/plugin-security.zod.ts#SBOMSchema (const)",
     "SEED_WRITE_EXECUTION_CONTEXT": "src/kernel/execution-context.zod.ts#SEED_WRITE_EXECUTION_CONTEXT (const)",
+    "SEMVER_SHAPED_LOWERCASE_VERSION_PATTERN": "src/kernel/version-grammar.ts#SEMVER_SHAPED_LOWERCASE_VERSION_PATTERN (const)",
+    "SEMVER_SHAPED_VERSION_PATTERN": "src/kernel/version-grammar.ts#SEMVER_SHAPED_VERSION_PATTERN (const)",
     "SandboxConfig": "src/kernel/plugin-security-advanced.zod.ts#SandboxConfig (type)",
     "SandboxConfigParsed": "src/kernel/plugin-security-advanced.zod.ts#SandboxConfigParsed (type)",
     "SandboxConfigSchema": "src/kernel/plugin-security-advanced.zod.ts#SandboxConfigSchema (const)",
 
@@ -140,3 +140,4 @@ export * from './plugin-security.zod';
 export * from './execution-context.zod';
 export * from './metadata-create-seeds';
 export * from './functional-completeness';
+export * from './version-grammar';
@@ -2,6 +2,7 @@
 
 import { z } from 'zod';
 import { CORE_PLUGIN_TYPES } from './plugin.zod';
+import { MAJOR_MINOR_PATCH_VERSION_PATTERN } from './version-grammar';
 import { retiredKey } from '../shared/retired-key';
 import { strictObject } from '../shared/strict-object';
 import { formatSuggestion } from '../shared/suggestions.zod';
@@ -411,7 +412,7 @@ export const ManifestSchema = strictObject({
    * @example "1.0.0"
    * @example "2.1.0"
    */
-  version: z.string().regex(/^\d+\.\d+\.\d+$/).describe('Package version (semantic versioning)'),
+  version: z.string().regex(MAJOR_MINOR_PATCH_VERSION_PATTERN).describe('Package version (semantic versioning)'),
 
   /** 
    * Type of the package in the ObjectStack ecosystem.
 
@@ -3,6 +3,7 @@
 import { z } from 'zod';
 import { retiredKey } from '../shared/retired-key';
 import { MetadataManagerConfigSchema } from './metadata-loader.zod';
+import { MAJOR_MINOR_PATCH_VERSION_PATTERN } from './version-grammar';
 import { ActionSchema } from '../ui/action.zod';
 
 /**
@@ -646,7 +647,7 @@ export const MetadataPluginManifestSchema = lazySchema(() => z.object({
   name: z.literal('ObjectStack Metadata Service').describe('Plugin name'),
 
   /** Plugin version */
-  version: z.string().regex(/^\d+\.\d+\.\d+$/).describe('Plugin version'),
+  version: z.string().regex(MAJOR_MINOR_PATCH_VERSION_PATTERN).describe('Plugin version'),
 
   /** Plugin type */
   type: z.literal('standard').describe('Plugin type'),
 
@@ -2,6 +2,7 @@
 
 import { z } from 'zod';
 import { PluginCapabilityManifestSchema } from './plugin-capability.zod';
+import { MAJOR_MINOR_PATCH_VERSION_PATTERN } from './version-grammar';
 
 /**
  * # Plugin Registry Protocol
@@ -155,7 +156,7 @@ export const PluginRegistryEntrySchema = lazySchema(() => z.object({
   /**
    * Current version
    */
-  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  version: z.string().regex(MAJOR_MINOR_PATCH_VERSION_PATTERN),
 
   /**
    * Plugin display name
 
@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { z } from 'zod';
+import { MAJOR_MINOR_PATCH_VERSION_PATTERN } from './version-grammar';
 
 /**
  * Plugin Validator Protocol
@@ -141,7 +142,7 @@ export const PluginMetadataSchema = lazySchema(() => z.object({
   /**
    * Plugin version (semver)
    */
-  version: z.string().regex(/^\d+\.\d+\.\d+$/).optional().describe('Semantic version (e.g., 1.0.0)'),
+  version: z.string().regex(MAJOR_MINOR_PATCH_VERSION_PATTERN).optional().describe('Semantic version (e.g., 1.0.0)'),
 
   /**
    * Plugin dependencies (array of plugin names)