feat(registry): extract _validate_module_id + raise MAX_MODULE_ID_LENGTH=192 (0.18.0)

Folded into the in-flight 0.18.0 release. All items now in CHANGELOG.md
[0.18.0] - 2026-04-08.

Changed:
- MAX_MODULE_ID_LENGTH raised from 128 to 192 (apcore.registry.registry).
  Tracks PROTOCOL_SPEC §2.7 EBNF constraint #1 update. Module IDs valid
  before this change remain valid; only the upper bound moved. Forward-
  compatible relaxation: older 0.17.x/0.18.x readers will reject IDs in
  the 129-192 range emitted by this version.
- Registry.register() and Registry.register_internal() now share a
  _validate_module_id() helper that runs validation in canonical order:
  empty → EBNF pattern → length → reserved word per-segment. The
  reserved-word check is the only step register_internal() skips (so sys
  modules can use the system.* prefix); empty/pattern/length/duplicate
  now apply uniformly. Aligned cross-language with apcore-typescript and
  apcore-rust.
- register_internal() now enforces empty/pattern/length/duplicate checks.
  Previously bypassed every validation step. Production callers
  (apcore.sys_modules.*) all use canonical-shape IDs so no in-tree
  caller is broken; external adapters that used register_internal as a
  generic escape hatch should review.
- Duplicate registration error message canonicalized to
  "Module ID '<id>' is already registered" (was "Module already exists:
  <id>" for register_internal). Both register() and register_internal()
  now emit the same message. Byte-aligned with apcore-rust and
  apcore-typescript.

Added:
- Pipeline preset builders re-exported at package root:
  build_standard_strategy, build_internal_strategy, build_testing_strategy,
  build_performance_strategy, build_minimal_strategy. These functions
  existed in apcore.builtin_steps but were not in apcore.__all__. Parity
  with apcore-typescript (buildXxxStrategy) and apcore-rust
  (build_xxx_strategy at crate root).
- TestRegisterInternalValidation test class in
  tests/registry/test_registry.py (6 parity tests) + two new
  test_pipeline_preset_builders_* tests in tests/test_public_api.py +
  tests/test_public_api.py EXPECTED_NAMES updated.
- tests/sys_modules/test_control.py: test_reload_module_calls_safe_unregister
  now also mocks register_internal since the re-registration path now
  enforces the duplicate-ID check (the test mocks safe_unregister so the
  slot is never actually cleared).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signed-off-by: tercel <tercel.yi@gmail.com>

Author: tercel

CHANGELOG.md

@@ -5,7 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.18.0] - 2026-04-07
+## [0.18.0] - 2026-04-08
+
+### Added
+
+- **Pipeline preset builders re-exported at package root** — `build_standard_strategy`, `build_internal_strategy`, `build_testing_strategy`, `build_performance_strategy`, `build_minimal_strategy` are now importable directly from `apcore`. These functions existed in `apcore.builtin_steps` but were not previously in `apcore.__all__`. Parity with apcore-typescript (`buildXxxStrategy`) and apcore-rust (`build_xxx_strategy` at the crate root).
+- **`TestRegisterInternalValidation`** test class in `tests/registry/test_registry.py` (6 parity tests covering empty rejection, pattern rejection, over-length rejection, reserved-word bypass, duplicate rejection, accept-at-max-length) plus `test_pipeline_preset_builders_*` in `tests/test_public_api.py`.
+
+### Changed
+
+- **`MAX_MODULE_ID_LENGTH` raised from 128 to 192** (`apcore.registry.registry`). Tracks PROTOCOL_SPEC §2.7 EBNF constraint #1 update — accommodates Java/.NET deep-namespace FQN-derived IDs while remaining filesystem-safe (`192 + len('.binding.yaml') = 205 < 255`-byte filename limit on ext4/xfs/NTFS/APFS/btrfs). Module IDs valid before this change remain valid; only the upper bound moved. **Forward-compatible relaxation:** older 0.17.x/0.18.x readers will reject IDs in the 129–192 range emitted by this version.
+- **`Registry.register()` and `Registry.register_internal()` now share a `_validate_module_id()` helper** that runs validation in canonical order (empty → EBNF pattern → length → reserved word per-segment). The reserved-word check is the only step `register_internal()` skips (so sys modules can use the `system.*` prefix); empty/pattern/length/duplicate now apply uniformly. Aligned cross-language with apcore-typescript and apcore-rust.
+- **`register_internal()` now enforces empty / pattern / length / duplicate checks.** Previously bypassed every validation step. Production callers (`apcore.sys_modules.*`) all use canonical-shape IDs so no in-tree caller is broken; external adapters that used `register_internal` as a generic escape hatch should review.
+- **Duplicate registration error message canonicalized** to `"Module ID '<id>' is already registered"` (was `"Module already exists: <id>"` for `register_internal`). Both `register()` and `register_internal()` now emit the same message via the shared error path. Aligned with apcore-rust and apcore-typescript byte-for-byte.
 
 ### Removed (BREAKING)
 

src/apcore/__init__.py

@@ -206,6 +206,15 @@
     unregister_step_type,
 )
 
+# Pipeline Preset Builders (parity with apcore-typescript and apcore-rust)
+from apcore.builtin_steps import (
+    build_internal_strategy,
+    build_minimal_strategy,
+    build_performance_strategy,
+    build_standard_strategy,
+    build_testing_strategy,
+)
+
 # Trace Context
 from apcore.trace_context import TraceContext, TraceParent
 
@@ -557,6 +566,12 @@ def enable(module_id: str, reason: str = "Enabled via APCore client") -> dict[st
     "unregister_step_type",
     "registered_step_types",
     "build_strategy_from_config",
+    # Pipeline Preset Builders (parity with apcore-typescript / apcore-rust)
+    "build_standard_strategy",
+    "build_internal_strategy",
+    "build_testing_strategy",
+    "build_performance_strategy",
+    "build_minimal_strategy",
     # System Modules
     "register_sys_modules",
     "register_subscriber_type",

src/apcore/registry/registry.py

@@ -103,7 +103,7 @@ def validate(self, module: Any) -> list[str]:
         ...
 
 
-MAX_MODULE_ID_LENGTH = 128
+MAX_MODULE_ID_LENGTH = 192
 
 RESERVED_WORDS = frozenset({"system", "internal", "core", "apcore", "plugin", "schema", "acl"})
 
@@ -118,6 +118,48 @@ def validate(self, module: Any) -> list[str]:
 ]
 
 
+def _validate_module_id(module_id: str, *, allow_reserved: bool = False) -> None:
+    """Validate a module ID against PROTOCOL_SPEC §2.7 in canonical order.
+
+    Order: empty → pattern → length → reserved (per-segment).
+    Duplicate detection is the caller's responsibility (it requires registry
+    state).
+
+    Args:
+        module_id: Candidate module ID to validate.
+        allow_reserved: When True, the per-segment reserved word check is
+            skipped — used by ``Registry.register_internal`` to allow sys
+            modules to use the ``system.*`` prefix. All other validations
+            (empty, pattern, length) still apply.
+
+    Raises:
+        InvalidInputError: On any validation failure.
+
+    Aligned with ``apcore-typescript._validateModuleId`` and
+    ``apcore::registry::registry::validate_module_id``.
+    """
+    # 1. empty check
+    if not module_id:
+        raise InvalidInputError(message="module_id must be a non-empty string")
+
+    # 2. EBNF pattern check
+    if not MODULE_ID_PATTERN.match(module_id):
+        raise InvalidInputError(
+            f"Invalid module ID: '{module_id}'. Must match pattern: "
+            f"{MODULE_ID_PATTERN.pattern} (lowercase, digits, underscores, dots only; no hyphens)"
+        )
+
+    # 3. length check
+    if len(module_id) > MAX_MODULE_ID_LENGTH:
+        raise InvalidInputError(f"Module ID exceeds maximum length of {MAX_MODULE_ID_LENGTH}: {len(module_id)}")
+
+    # 4. reserved word per-segment check (skipped for register_internal)
+    if not allow_reserved:
+        for segment in module_id.split("."):
+            if segment in RESERVED_WORDS:
+                raise InvalidInputError(f"Module ID contains reserved word: '{segment}'")
+
+
 class Registry:
     """Central module registry for discovering, registering, and querying modules."""
 
@@ -422,20 +464,16 @@ def register(
             metadata: Optional metadata dict (may include x-compatible-versions, x-deprecation).
 
         Raises:
-            InvalidInputError: If module_id is already registered (non-versioned).
+            InvalidInputError: If module_id is empty, malformed, exceeds the
+                length limit, contains a reserved word, or is already
+                registered (non-versioned).
             RuntimeError: If module.on_load() fails (propagated).
-        """
-        if not module_id:
-            raise InvalidInputError(message="module_id must be a non-empty string")
-
-        if not MODULE_ID_PATTERN.match(module_id):
-            raise InvalidInputError(
-                f"Invalid module ID: '{module_id}'. Must match pattern: "
-                f"{MODULE_ID_PATTERN.pattern} (lowercase, digits, underscores, dots only; no hyphens)"
-            )
 
-        if len(module_id) > MAX_MODULE_ID_LENGTH:
-            raise InvalidInputError(f"Module ID exceeds maximum length of {MAX_MODULE_ID_LENGTH}: {len(module_id)}")
+        Validation order (PROTOCOL_SPEC §2.7, aligned with apcore-typescript
+        and apcore-rust): empty → pattern → length → reserved (per-segment)
+        → duplicate.
+        """
+        _validate_module_id(module_id, allow_reserved=False)
 
         _ensure_schema_adapter(module)
 
@@ -1009,12 +1047,31 @@ def get_module_metadata(self, module_id: str) -> dict[str, Any]:
             return dict(self._module_meta.get(module_id, {}))
 
     def register_internal(self, module_id: str, module: Any) -> None:
-        """Register a module bypassing reserved word validation.
+        """Register a sys/internal module that bypasses **only** the reserved
+        word check.
+
+        All other PROTOCOL_SPEC §2.7 validations (empty, EBNF pattern, length,
+        duplicate) still apply. The intended use case is registering modules
+        under reserved prefixes like ``system.health`` or
+        ``system.control.toggle_feature`` from ``apcore.sys_modules``.
 
-        Used by sys modules that use the reserved 'system.' prefix.
+        Aligned with apcore-typescript ``Registry.registerInternal`` and
+        apcore-rust ``Registry::register_internal``.
+
+        Raises:
+            InvalidInputError: If module_id is empty, malformed, exceeds the
+                length limit, or is already registered.
+            RuntimeError: If module.on_load() fails (propagated).
         """
+        _validate_module_id(module_id, allow_reserved=True)
+
         _ensure_schema_adapter(module)
         with self._lock:
+            if module_id in self._modules:
+                # Aligned with apcore-typescript / apcore-rust and the canonical
+                # message produced by detect_id_conflicts for the public
+                # `register()` path.
+                raise InvalidInputError(message=f"Module ID '{module_id}' is already registered")
             self._modules[module_id] = module
             self._lowercase_map[module_id.lower()] = module_id
         self._trigger_event("register", module_id, module)

tests/registry/test_registry.py

@@ -1111,9 +1111,13 @@ def test_custom_validator_with_default_discover(self, tmp_path: Path) -> None:
 
 
 class TestRegistryConstants:
-    def test_max_module_id_length_is_128(self) -> None:
-        """MAX_MODULE_ID_LENGTH is 128."""
-        assert MAX_MODULE_ID_LENGTH == 128
+    def test_max_module_id_length_matches_spec(self) -> None:
+        """MAX_MODULE_ID_LENGTH matches PROTOCOL_SPEC §2.7 EBNF constraint #1 (192).
+
+        Filesystem-safe: 192 + len('.binding.yaml')=13 = 205 < 255-byte filename limit.
+        Bumped from 128 to accommodate Java/.NET deep-namespace FQN-derived IDs.
+        """
+        assert MAX_MODULE_ID_LENGTH == 192
 
     def test_max_module_id_length_is_int(self) -> None:
         """MAX_MODULE_ID_LENGTH is an integer."""
@@ -1155,3 +1159,42 @@ def test_module_id_at_max_length_accepted(self) -> None:
         exact_id = "a" * MAX_MODULE_ID_LENGTH
         reg.register(exact_id, _ValidModule())
         assert reg.has(exact_id)
+
+
+# ===== register_internal — bypasses ONLY reserved word check =====
+# (parity with apcore-typescript and apcore-rust)
+
+
+class TestRegisterInternalValidation:
+    def test_register_internal_accepts_reserved_first_segment(self) -> None:
+        reg = Registry()
+        reg.register_internal("system.health", _ValidModule())
+        assert reg.has("system.health")
+
+    def test_register_internal_accepts_reserved_any_segment(self) -> None:
+        reg = Registry()
+        reg.register_internal("myapp.system.config", _ValidModule())
+        assert reg.has("myapp.system.config")
+
+    def test_register_internal_still_rejects_empty(self) -> None:
+        reg = Registry()
+        with pytest.raises(InvalidInputError, match="non-empty"):
+            reg.register_internal("", _ValidModule())
+
+    def test_register_internal_still_rejects_invalid_pattern(self) -> None:
+        reg = Registry()
+        for bad_id in ["INVALID-ID", "1abc", "Module", "a..b", ".leading", "trailing.", "has space"]:
+            with pytest.raises(InvalidInputError, match="Invalid module ID|Must match pattern"):
+                reg.register_internal(bad_id, _ValidModule())
+
+    def test_register_internal_still_rejects_over_length(self) -> None:
+        reg = Registry()
+        overlong = "a" * (MAX_MODULE_ID_LENGTH + 1)
+        with pytest.raises(InvalidInputError, match="maximum length"):
+            reg.register_internal(overlong, _ValidModule())
+
+    def test_register_internal_rejects_duplicate(self) -> None:
+        reg = Registry()
+        reg.register_internal("system.dup", _ValidModule())
+        with pytest.raises(InvalidInputError, match="already registered"):
+            reg.register_internal("system.dup", _ValidModule())

tests/sys_modules/test_control.py

@@ -321,8 +321,14 @@ def test_reload_module_calls_safe_unregister(self) -> None:
         mod = _make_reload_module(registry=registry)
 
         new_module = _FakeModuleV2()
+        # `register_internal` now enforces the duplicate check (aligned with
+        # apcore-typescript / apcore-rust). Because `safe_unregister` is mocked
+        # to return True without actually removing the slot, we must also mock
+        # `register_internal` so the re-registration doesn't trip the new
+        # duplicate guard. This test only cares about the safe_unregister call.
         with (
             patch.object(registry, "safe_unregister", return_value=True) as mock_unreg,
+            patch.object(registry, "register_internal"),
             patch.object(mod, "_rediscover_module", return_value=new_module),
         ):
             mod.execute(

tests/test_public_api.py

@@ -311,6 +311,39 @@ def test_version_is_set(self):
         assert isinstance(apcore.__version__, str)
         assert re.match(r"^\d+\.\d+\.\d+", apcore.__version__)
 
+    # -- Pipeline preset builders (parity with apcore-typescript / apcore-rust) --
+    # Regression for sync finding A-006: Python previously only exported
+    # build_strategy_from_config; the 5 named-preset builders existed in
+    # apcore.builtin_steps but were not re-exported to the package root.
+
+    def test_pipeline_preset_builders_importable_from_package_root(self):
+        from apcore import (
+            build_internal_strategy,
+            build_minimal_strategy,
+            build_performance_strategy,
+            build_standard_strategy,
+            build_testing_strategy,
+        )
+
+        for fn in (
+            build_standard_strategy,
+            build_internal_strategy,
+            build_testing_strategy,
+            build_performance_strategy,
+            build_minimal_strategy,
+        ):
+            assert callable(fn)
+
+    def test_pipeline_preset_builders_in_all(self):
+        for name in (
+            "build_standard_strategy",
+            "build_internal_strategy",
+            "build_testing_strategy",
+            "build_performance_strategy",
+            "build_minimal_strategy",
+        ):
+            assert name in apcore.__all__, f"{name} missing from apcore.__all__"
+
 
 class TestPublicAPIAll:
     """Verify __all__ is comprehensive and matches actual exports."""
@@ -514,6 +547,12 @@ class TestPublicAPIAll:
         "unregister_step_type",
         "registered_step_types",
         "build_strategy_from_config",
+        # Pipeline Preset Builders (parity with apcore-typescript / apcore-rust)
+        "build_standard_strategy",
+        "build_internal_strategy",
+        "build_testing_strategy",
+        "build_performance_strategy",
+        "build_minimal_strategy",
         # Config Bus (0.15.0)
         "ConfigBindError",
         "ConfigEnvMapConflictError",