Add ErrorCodes, ContextFactory, REGISTRY_EVENTS, MODULE_ID_PATTERN, and Executor.from_registry()

[tercel]

Summary

Real-world integrations (django-apcore) revealed that apcore-python lacks several standard constants, protocols, and convenience utilities needed for framework integration.

Issues Addressed

1. ErrorCodes Constant (P1 — tiptap-apcore ISSUE-003)

Problem: Error codes are magic strings. No exported constant for consumers to reference.

Fix: Add immutable ErrorCodes class to src/apcore/errors.py with all 26 error codes, __setattr__ and __delattr__ overrides to prevent mutation.

2. ContextFactory Protocol (P0 — django-apcore Django-2.1)

Problem: No standard adapter pattern for creating Context from HTTP requests. Django, Flask, FastAPI integrations each invented their own approach. Authenticated user identity cannot reach module execution.

Fix: Add @runtime_checkable ContextFactory Protocol to src/apcore/context.py:

@runtime_checkable
class ContextFactory(Protocol):
    def create_context(self, request: Any) -> Context: ...

3. REGISTRY_EVENTS and MODULE_ID_PATTERN (P0 — tiptap-apcore ISSUE-001, ISSUE-002)

Problem: Registry event names not standardized; module IDs not validated (hyphens allowed, breaking MCP normalization).

Fix:

• REGISTRY_EVENTS dict with "REGISTER" / "UNREGISTER" keys
• MODULE_ID_PATTERN compiled regex: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
• register() validates module IDs against MODULE_ID_PATTERN, rejecting hyphens

4. Executor.from_registry() Convenience Factory (P1 — django-apcore Django-2.3)

Problem: Creating a properly configured Executor is undocumented. Framework integrations pass raw Registry to serve(), bypassing the middleware/ACL/validation pipeline.

Fix: Add @classmethod Executor.from_registry():

@classmethod
def from_registry(cls, registry, middlewares=None, acl=None, config=None) -> Executor:
    return cls(registry=registry, middlewares=middlewares, acl=acl, config=config)

Files Changed

• src/apcore/errors.py — Add ErrorCodes class
• src/apcore/context.py — Add ContextFactory Protocol
• src/apcore/registry/registry.py — Add REGISTRY_EVENTS, MODULE_ID_PATTERN, module ID validation
• src/apcore/executor.py — Add from_registry() classmethod
• src/apcore/__init__.py — Export new symbols

Source

• django-apcore/docs/django-apcore/upstream-sdk-analysis.md (Django-2.1, 2.3, 2.5)
• apcore-mcp-typescript/docs/issues/tiptap-apcore-findings.md (ISSUE-001, 002, 003)