chore: update version numbers and improve documentation across multiple files

Author: tercel

PROTOCOL_SPEC.md

@@ -2,10 +2,10 @@
 
 > **Canonical Specification** - This document is the authoritative specification for the apcore protocol
 
-> Version: 1.0.0-draft
+> Version: 1.2.0-draft
 > Status: Draft Specification (RFC 2119 Conformant)
 > Stability: Specification content is stable, pending reference implementation verification
-> Last Updated: 2026-02-07
+> Last Updated: 2026-02-22
 
 ---
 

docs/api/context-object.md

@@ -28,7 +28,7 @@ if TYPE_CHECKING:
     from apcore import Executor
 
 
-@dataclass
+@dataclass(frozen=True)
 class Identity:
     """Caller identity (human/service/AI generic)"""
 
@@ -39,7 +39,8 @@ class Identity:
     type: str = "user"  # user | service | agent | api_key | system
 
     # Role list (ACL engine dependency)
-    roles: list[str] = field(default_factory=list)
+    # Implementations SHOULD use immutable collection types (e.g. Python tuple, TypeScript readonly array)
+    roles: tuple[str, ...] = field(default_factory=tuple)
 
     # Extended attributes (business fields like tenant_id, email)
     attrs: dict[str, Any] = field(default_factory=dict)
@@ -68,9 +69,10 @@ class Context:
     # Caller identity (ACL engine dependency)
     identity: Identity | None = None
 
-    # ====== Logging and redaction ======
+    # ── SHOULD-level members (optional for implementations) ──────────
 
     # Context-aware logger (automatically injects trace_id, module_id, caller_id)
+    # Level: SHOULD (not MUST). Implementations may provide equivalent functionality via a standalone ContextLogger class.
     @property
     def logger(self) -> "ContextLogger":
         """Returns a logger that automatically injects context information"""
@@ -633,12 +635,12 @@ from datetime import datetime
 import uuid
 
 
-@dataclass
+@dataclass(frozen=True)
 class Identity:
     """Caller identity"""
     id: str
     type: str = "user"
-    roles: list[str] = field(default_factory=list)
+    roles: tuple[str, ...] = field(default_factory=tuple)
     attrs: dict[str, Any] = field(default_factory=dict)
 
 

docs/api/executor-api.md

@@ -35,7 +35,7 @@ class Executor:
     def call(
         self,
         module_id: str,
-        inputs: dict[str, Any],
+        inputs: dict[str, Any] | None = None,
         context: Context | None = None
     ) -> dict[str, Any]:
         """
@@ -63,7 +63,7 @@ class Executor:
     async def call_async(
         self,
         module_id: str,
-        inputs: dict[str, Any],
+        inputs: dict[str, Any] | None = None,
         context: Context | None = None
     ) -> dict[str, Any]:
         """
@@ -75,6 +75,21 @@ class Executor:
         """
         ...
 
+    async def stream(
+        self,
+        module_id: str,
+        inputs: dict[str, Any] | None = None,
+        context: Context | None = None
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        Stream module output chunk by chunk
+
+        Yields partial results as they become available.
+        Calls the module's stream() method if defined,
+        otherwise falls back to standard execute().
+        """
+        ...
+
     def validate(
         self,
         module_id: str,

docs/api/module-interface.md

@@ -391,14 +391,15 @@ class SendEmailModule(Module):
 from dataclasses import dataclass
 
 
-@dataclass
+@dataclass(frozen=True)
 class ModuleAnnotations:
     """Module behavior annotations"""
     readonly: bool = False          # Read-only, no side effects
     destructive: bool = False       # Has destructive operations
     idempotent: bool = False        # Idempotent, safe to call repeatedly
     requires_approval: bool = False # Requires human confirmation
     open_world: bool = True         # Involves external systems
+    streaming: bool = False         # Supports streaming output
 ```
 
 | Field | Default | Meaning | AI Behavior |
@@ -408,6 +409,7 @@ class ModuleAnnotations:
 | `idempotent` | `False` | Repeated calls have no additional side effects | `True` → Safe to retry |
 | `requires_approval` | `False` | Requires human confirmation | `True` → Seek consent |
 | `open_world` | `True` | Connects to external systems | `True` → May be slow |
+| `streaming` | `False` | Supports streaming chunk-by-chunk output | `True` → Read output incrementally |
 
 ```python
 # Query module - read-only, safe

docs/api/registry-api.md

@@ -73,6 +73,14 @@ class Registry:
         ...
 
     # ============ Schema Query and Export ============
+    #
+    # Note: In implementations, these schema methods MAY be provided as
+    # independent helper functions rather than Registry methods, e.g.:
+    #   get_schema(registry, module_id)
+    #   export_schema(registry, module_id, format=...)
+    # The Registry interface below defines the recommended convenience
+    # interface. Implementations may choose standalone function form
+    # if it better fits their architecture.
 
     def get_schema(self, module_id: str) -> dict | None:
         """Get module Schema (structured dict, for in-program processing)"""
@@ -669,6 +677,8 @@ Steps:
 
 ### 9.1 Custom Discoverer
 
+> **Reserved — Not Implemented.** The `set_discoverer()` API below is a reserved design; current SDKs do not support it. Documentation is retained for future reference.
+
 ```python
 from apcore import Registry, ModuleDiscoverer
 
@@ -696,6 +706,8 @@ registry.discover()
 
 ### 9.2 Module Validator
 
+> **Reserved — Not Implemented.** The `set_validator()` API below is a reserved design; current SDKs do not support it. Documentation is retained for future reference.
+
 ```python
 from apcore import Registry, ModuleValidator
 
@@ -723,6 +735,8 @@ registry.discover()
 
 ### 9.3 Hot Reload (Development Mode)
 
+> **Reserved — Not Implemented.** The `watch()` / `unwatch()` API below is a reserved design; current SDKs do not support it. Documentation is retained for future reference.
+
 ```python
 from apcore import Registry
 

docs/architecture.md

@@ -413,30 +413,47 @@ Throw ModuleError
 apcore/
 ├── __init__.py           # Public API
 ├── module.py             # Module base class
-├── registry.py           # Registry implementation
+├── decorator.py          # Module decorator and FunctionModule
+├── bindings.py           # YAML binding loader for zero-code integration
 ├── executor.py           # Executor implementation
 ├── context.py            # Context definition
 ├── acl.py                # ACL implementation
-├── schema.py             # Schema utilities
 ├── errors.py             # Exception definitions
 ├── config.py             # Config loading
 │
-├── discovery/            # Module discovery
+├── registry/             # Module discovery & registration
 │   ├── __init__.py
-│   ├── discoverer.py     # Discoverer interface
-│   ├── python.py         # Python discoverer
-│   └── id_map.py         # ID Map handling
+│   ├── registry.py       # Central Registry class
+│   ├── types.py          # ModuleDescriptor, DiscoveredModule, DependencyInfo
+│   ├── scanner.py        # Directory/file scanning
+│   ├── validation.py     # Module interface validation
+│   ├── metadata.py       # Module metadata extraction
+│   ├── dependencies.py   # Dependency resolution & load order
+│   ├── entry_point.py    # Entry point resolution
+│   └── schema_export.py  # Schema export helpers
 │
-├── validation/           # Validation
+├── schema/               # Schema processing
 │   ├── __init__.py
-│   ├── module.py         # Module interface validation
-│   └── schema.py         # Schema validation
+│   ├── types.py          # SchemaStrategy, ExportProfile, type definitions
+│   ├── loader.py         # Schema loading
+│   ├── validator.py      # Schema validation
+│   ├── exporter.py       # Schema export (JSON/YAML)
+│   ├── ref_resolver.py   # $ref resolution
+│   ├── strict.py         # Strict mode transformation
+│   └── annotations.py    # x-* annotation handling
 │
 ├── middleware/           # Middleware
-│   ├── __init__.py       # Middleware base class + public API
-│   ├── logging.py        # Logging middleware
-│   ├── metrics.py        # Metrics middleware
-│   └── retry.py          # Retry middleware
+│   ├── __init__.py       # Public API
+│   ├── base.py           # Middleware base class
+│   ├── adapters.py       # BeforeMiddleware, AfterMiddleware adapters
+│   ├── manager.py        # MiddlewareManager pipeline engine
+│   └── logging.py        # Logging middleware
+│
+├── observability/        # Observability
+│   ├── __init__.py
+│   ├── tracing.py        # Distributed tracing
+│   ├── metrics.py        # Metrics collection
+│   └── context_logger.py # Context-aware logging
 │
 └── utils/                # Utilities
     ├── __init__.py
@@ -473,11 +490,14 @@ my-project/
 
 ### 5.1 Custom Discoverer
 
+> **Note:** This example shows the conceptual interface pattern. The actual
+> Python SDK uses a function-based API (`apcore.registry.scanner.scan_extensions`).
+
 ```python
-from apcore.discovery import ModuleDiscoverer
+from apcore.registry.scanner import scan_extensions
 
 
-class RemoteDiscoverer(ModuleDiscoverer):
+class RemoteDiscoverer:
     """Discover modules from remote service"""
 
     def discover(self, config: dict) -> list[tuple[str, Type[Module]]]:
@@ -492,15 +512,18 @@ class RemoteDiscoverer(ModuleDiscoverer):
 
 ### 5.2 Custom Validator
 
+> **Note:** This example shows the conceptual interface pattern. The actual
+> Python SDK uses a function-based API (`apcore.registry.validation.validate_module`).
+
 ```python
-from apcore.validation import ModuleValidator
+from apcore.registry.validation import validate_module
 
 
-class StrictValidator(ModuleValidator):
+class StrictValidator:
     """Strict module validator"""
 
     def validate(self, module_class: Type[Module]) -> list[str]:
-        errors = super().validate(module_class)
+        errors = validate_module(module_class)
 
         # Custom rules
         if len(module_class.tags) == 0:
@@ -643,7 +666,7 @@ def sync_caller():
 - **ACL check timeout**: independent timing (default 1 second)
 - Timing starts from first `before()` middleware
 
-**Cancellation Strategy:**
+**Cancellation Strategy:** **Future (Not Implemented)** — The following is a planned design; current SDKs have not yet implemented this.
 
 1. **Cooperative cancellation** (recommended):
    - Module checks `context.cancel_token.is_cancelled()` and actively exits
@@ -673,7 +696,7 @@ See [PROTOCOL_SPEC §11.7.4 Timeout Enforcement](../PROTOCOL_SPEC.md#1174-timeou
 
 - `context.data` across entire call chain is **the same** dict object (reference sharing)
 - Parent module modifications to `context.data` visible to child modules, and vice versa
-- When `derive()` creates new Context, `data` field copies reference (not deep copy)
+- When `child()` creates new Context, `data` field copies reference (not deep copy)
 
 **Isolation:**
 
@@ -688,7 +711,7 @@ context1 = Context(data={})
 executor.call("module_a", {}, context1)
 # module_a internally:
 context.data["key"] = "value_a"
-sub_context = context.derive("module_b")
+sub_context = context.child("module_b")
 executor.call("module_b", {}, sub_context)
 # module_b reads "value_a" (reference sharing)
 

docs/spec/conformance.md

@@ -490,7 +490,7 @@ implementation:
   name: "apcore-python"              # Implementation name
   version: "0.1.0"                   # Implementation version
   language: "python"                 # Implementation language
-  spec_version: "1.0.0-draft"       # Corresponding PROTOCOL_SPEC version
+  spec_version: "1.2.0-draft"       # Corresponding PROTOCOL_SPEC version
   maintainer: "AI Partner Up"        # Maintainer
   repository: "https://github.com/aipartnerup/apcore-python"  # Repository address