apagea 2026.10.1rc2__tar.gz

apagea-2026.10.1rc2/ActionBase.Dockerfile

@@ -0,0 +1,34 @@
+# Shared operating-system and SDK layers, built once per platform release.
+ARG BASE=ubuntu:26.04
+FROM ghcr.io/astral-sh/uv:0.12.18 AS uv
+FROM ${BASE} AS system
+RUN DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends python3 ca-certificates libstdc++6 && rm -rf /var/lib/apt/lists/*
+RUN python3 -c 'import sys; assert sys.version_info[:2] == (3,14)'
+ENV PATH=/opt/venv/bin:${PATH} PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_DISABLE_PIP_VERSION_CHECK=1
+
+FROM system AS builder
+RUN DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends python3-venv python3-dev build-essential && rm -rf /var/lib/apt/lists/*
+RUN python3 -m venv /opt/venv
+COPY base-requirements.txt /tmp/base-requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip pip install -r /tmp/base-requirements.txt
+COPY pyproject.toml README.md /sdk/
+COPY apagea/ /sdk/apagea/
+ARG VERSION
+RUN test -n "$VERSION" && SETUPTOOLS_SCM_PRETEND_VERSION_FOR_APAGEA="$VERSION" pip install --no-deps --no-build-isolation /sdk && pip check
+RUN python -c 'import os; from importlib.metadata import version; assert version("apagea") == os.environ["VERSION"]' && mkdir -p /opt/apagea && python -c 'from importlib.metadata import distributions; print("\n".join(sorted(d.metadata["Name"] + "==" + d.version for d in distributions())))' > /opt/apagea/constraints.txt
+# Utilities change independently of the compiler, dependencies and SDK.
+COPY --from=uv /uv /usr/local/bin/uv
+ARG COMMIT=unknown
+ARG REPOSITORY=apageadev/apagea
+LABEL org.opencontainers.image.source="https://github.com/${REPOSITORY}" org.opencontainers.image.version="${VERSION}" org.opencontainers.image.revision="${COMMIT}" dev.apagea.base.kind="builder" dev.apagea.sdk.version="${VERSION}" dev.apagea.python.version="3.14"
+
+FROM system AS runtime
+COPY --from=builder /opt/venv /opt/venv
+RUN pip uninstall -y pip setuptools wheel
+ARG VERSION
+ARG COMMIT=unknown
+ARG REPOSITORY=apageadev/apagea
+LABEL org.opencontainers.image.source="https://github.com/${REPOSITORY}" org.opencontainers.image.version="${VERSION}" org.opencontainers.image.revision="${COMMIT}" dev.apagea.base.kind="runtime" dev.apagea.sdk.version="${VERSION}" dev.apagea.python.version="3.14"
+USER 65532:65532
+WORKDIR /tmp
+ENTRYPOINT ["python", "-m", "apagea.actions"]

apagea-2026.10.1rc2/Dockerfile

@@ -0,0 +1,30 @@
+# Both bases are resolved and validated by the CLI before this build starts.
+ARG BUILDER=scratch
+ARG RUNTIME=scratch
+FROM ${BUILDER} AS build
+ARG RUNTIME=scratch
+ARG ACTION_PLATFORM
+ARG RUNTIME_IDENTITY
+ENV ACTION_BASE=${RUNTIME_IDENTITY} ACTION_PLATFORM=${ACTION_PLATFORM}
+COPY metadata/ /metadata/
+# BEGIN dependencies
+RUN --mount=type=cache,target=/root/.cache/pip \
+    python -m apagea.actions.build_dependencies /metadata/pyproject.toml --build-only > /metadata/requirements.txt && \
+    if [ -f /metadata/uv.lock ]; then \
+      cd /metadata && UV_PYTHON_DOWNLOADS=never uv export --locked --no-dev --no-emit-project --no-emit-package apagea --no-editable --format requirements-txt --output-file /metadata/locked.txt >/dev/null && \
+      pip install --constraint /opt/apagea/constraints.txt -r /metadata/locked.txt && \
+      python -m apagea.actions.build_dependencies --constraints > /metadata/constraints.txt && \
+      pip install --constraint /opt/apagea/constraints.txt --constraint /metadata/constraints.txt -r /metadata/requirements.txt; \
+    else pip install --constraint /opt/apagea/constraints.txt -r /metadata/requirements.txt; fi
+# END dependencies
+COPY source/ /source/
+ARG DEVELOPMENT=false
+ARG DIAGNOSTICS=detailed
+RUN --mount=type=cache,target=/root/.cache/pip pip install --constraint /opt/apagea/constraints.txt $(if [ -f /metadata/locked.txt ]; then printf "%s" "--constraint /metadata/constraints.txt"; fi) --no-build-isolation /source && if [ "$DEVELOPMENT" = "true" ]; then python -m apagea.actions.development --build /source --diagnostics "$DIAGNOSTICS"; else python -m apagea.actions build /source; fi && pip check
+RUN pip uninstall -y pip setuptools wheel
+FROM ${RUNTIME}
+COPY --from=build /opt/venv /opt/venv
+COPY --from=build /opt/apagea/action /opt/apagea/action
+USER 65532:65532
+WORKDIR /tmp
+ENTRYPOINT ["python", "-m", "apagea.actions"]

apagea-2026.10.1rc2/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: apagea
+Version: 2026.10.1rc2
+Summary: Official APAGEA Python SDK and typed Action runtime
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema<5,>=4.25
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: packaging==25.0
+Requires-Dist: cryptography<47,>=46
+
+# Apagea Python SDK
+
+The `apagea` distribution provides the typed Action runtime, extracted and adapted from Pyplines. Initial development version: `0.1.0.dev0` (unpublished).
+
+```python
+from pydantic import SecretStr
+from apagea.actions import Context, Inputs, Outputs
+
+class Request(Inputs):
+    message: str
+
+class Settings(Context):
+    api_token: SecretStr
+
+class Result(Outputs):
+    message: str
+
+def handler(inputs: Request, context: Settings) -> Result:
+    context.log.info("Processing request")
+    return Result(message=inputs.message)
+```
+
+Declare the handler in `[project.entry-points."apagea.action"]`. The Go CLI discovers/builds the interface in Docker through this SDK. Context model fields describe deployment-scoped Context requirements; invocation identity, scratch space, logging, and artifact staging are runtime facilities excluded from that schema.
+
+Logger methods are `debug`, `info`, `warn`, `error`, and `exception`, with no aliases. Records are bounded and thread-safe. Wrapped secret values are recursively masked, and known secret strings are redacted on a best-effort basis. Unwrapping/transformation is not tracked as taint. Do not write secrets to logs. Sensitive Context disables detailed local exception diagnostics; secret wrappers in public results retain Pydantic's masking. Remote protected outputs are sealed to the server, encrypted at rest, and exposed through separately authorized evidence endpoints.
+
+`apagea.fields` supplies Pydantic-compatible `TextInput`, `NumberInput`, `Text`, `Table`, `LineChart`, and `Download` helpers. Capture validates component field references and emits versioned metadata plus explicit field order. External clients can render these contracts; `apagea.blocks` is the preferred output-authoring surface, with `Metric`, `MetricValue`, `Status`, `TimeSeries`, `Table`, `Text`, and `Download`. Existing output helpers remain compatible. The server returns ordinary fields as JSON without prescribing rendering.
+
+`context.artifacts.add` stages bounded files from scratch space. Local limits are 16 files, 16 MiB per file, and 64 MiB total. Use the CLI's `--artifacts` to retain them after execution. Remote artifacts are retained by the server and downloaded through authenticated endpoints.
+
+A handler explicitly annotated `-> None` may complete without returning domain data. Its wire output is an empty object. A non-None return fails validation. A numeric field can use `Metric(format="compact")`; a `MetricValue` field can additionally return `value`, `previous`, and `comparison` for a comparative metric. Logger methods remain unchanged and have no aliases.
+
+```sh
+uv run --project apagea-sdk python -m unittest discover -s apagea-sdk/tests
+```
+
+See [authoring contract](../design/AUTHORING.md) and [working example](../examples/README.md).
+
+## Helpful failures
+
+Use `ActionError(message, code="action_failed", *, hint="")` for text intended for the person running the tool. Keep credentials and sensitive data out of all three public fields. Known secrets are additionally redacted by the SDK and server.
+
+```python
+raise ActionError(
+    "GitHub rejected the configured credential.",
+    "github_authentication_failed",
+    hint="Ask a Namespace administrator to update the credential.",
+) from error
+```
+
+Deployed failures automatically capture a protected exception chain and stack locations, including when Context contains secrets. These are sealed to the server and accessible only through separately authorized, audited diagnostic reads. Unexpected exception messages stay in that protected record. Local diagnostic behavior is unchanged. See [invocation diagnostics](../design/DIAGNOSTICS.md) for collection limits and security boundaries.

apagea-2026.10.1rc2/README.md

@@ -0,0 +1,51 @@
+# Apagea Python SDK
+
+The `apagea` distribution provides the typed Action runtime, extracted and adapted from Pyplines. Initial development version: `0.1.0.dev0` (unpublished).
+
+```python
+from pydantic import SecretStr
+from apagea.actions import Context, Inputs, Outputs
+
+class Request(Inputs):
+    message: str
+
+class Settings(Context):
+    api_token: SecretStr
+
+class Result(Outputs):
+    message: str
+
+def handler(inputs: Request, context: Settings) -> Result:
+    context.log.info("Processing request")
+    return Result(message=inputs.message)
+```
+
+Declare the handler in `[project.entry-points."apagea.action"]`. The Go CLI discovers/builds the interface in Docker through this SDK. Context model fields describe deployment-scoped Context requirements; invocation identity, scratch space, logging, and artifact staging are runtime facilities excluded from that schema.
+
+Logger methods are `debug`, `info`, `warn`, `error`, and `exception`, with no aliases. Records are bounded and thread-safe. Wrapped secret values are recursively masked, and known secret strings are redacted on a best-effort basis. Unwrapping/transformation is not tracked as taint. Do not write secrets to logs. Sensitive Context disables detailed local exception diagnostics; secret wrappers in public results retain Pydantic's masking. Remote protected outputs are sealed to the server, encrypted at rest, and exposed through separately authorized evidence endpoints.
+
+`apagea.fields` supplies Pydantic-compatible `TextInput`, `NumberInput`, `Text`, `Table`, `LineChart`, and `Download` helpers. Capture validates component field references and emits versioned metadata plus explicit field order. External clients can render these contracts; `apagea.blocks` is the preferred output-authoring surface, with `Metric`, `MetricValue`, `Status`, `TimeSeries`, `Table`, `Text`, and `Download`. Existing output helpers remain compatible. The server returns ordinary fields as JSON without prescribing rendering.
+
+`context.artifacts.add` stages bounded files from scratch space. Local limits are 16 files, 16 MiB per file, and 64 MiB total. Use the CLI's `--artifacts` to retain them after execution. Remote artifacts are retained by the server and downloaded through authenticated endpoints.
+
+A handler explicitly annotated `-> None` may complete without returning domain data. Its wire output is an empty object. A non-None return fails validation. A numeric field can use `Metric(format="compact")`; a `MetricValue` field can additionally return `value`, `previous`, and `comparison` for a comparative metric. Logger methods remain unchanged and have no aliases.
+
+```sh
+uv run --project apagea-sdk python -m unittest discover -s apagea-sdk/tests
+```
+
+See [authoring contract](../design/AUTHORING.md) and [working example](../examples/README.md).
+
+## Helpful failures
+
+Use `ActionError(message, code="action_failed", *, hint="")` for text intended for the person running the tool. Keep credentials and sensitive data out of all three public fields. Known secrets are additionally redacted by the SDK and server.
+
+```python
+raise ActionError(
+    "GitHub rejected the configured credential.",
+    "github_authentication_failed",
+    hint="Ask a Namespace administrator to update the credential.",
+) from error
+```
+
+Deployed failures automatically capture a protected exception chain and stack locations, including when Context contains secrets. These are sealed to the server and accessible only through separately authorized, audited diagnostic reads. Unexpected exception messages stay in that protected record. Local diagnostic behavior is unchanged. See [invocation diagnostics](../design/DIAGNOSTICS.md) for collection limits and security boundaries.

apagea-2026.10.1rc2/apagea/__init__.py

@@ -0,0 +1,15 @@
+"""Official APAGEA Python interface. Action authoring is available in apagea.actions."""
+def __getattr__(name):
+    # Metadata discovery is for tooling; bootstrap must not scan distributions
+    # before receiving its authorized invocation envelope.
+    if name == "__version__":
+        from importlib.metadata import version
+        value = version("apagea")
+        globals()[name] = value
+        return value
+    raise AttributeError(name)
+
+try:
+    from ._release import COMMIT as __commit__
+except ImportError:
+    __commit__ = "unknown"

apagea-2026.10.1rc2/apagea/actions/__init__.py

@@ -0,0 +1,4 @@
+from .contract import Inputs, Outputs, Context, ActionError
+from .artifacts import Artifact
+
+__all__ = ["Inputs", "Outputs", "Context", "ActionError", "Artifact"]

apagea-2026.10.1rc2/apagea/actions/__main__.py

@@ -0,0 +1,19 @@
+"""Command entry point for Action build and local execution."""
+import sys
+from .runtime import VERSION, LogWriter, run, load_handler
+
+
+def build(source, manifest_path=None):
+    from .build import build as discover
+    return discover(source, manifest_path)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3 and sys.argv[1] == "build":
+        try:
+            build(sys.argv[2])
+        except BaseException:
+            print("Action interface validation failed; check metadata, dependencies and handler annotations", file=sys.stderr)
+            raise SystemExit(1)
+    else:
+        raise SystemExit(run())

apagea-2026.10.1rc2/apagea/actions/artifacts.py

@@ -0,0 +1,65 @@
+"""Bounded artifact staging; remote upload belongs to the runner."""
+import hashlib
+import os
+from pathlib import Path
+from uuid import uuid4
+from pydantic import BaseModel, ConfigDict
+
+class Artifact(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    id: str
+    filename: str
+    media_type: str
+    size: int
+    sha256: str
+
+class ArtifactStore:
+    def __init__(self, scratch, destination):
+        self.scratch = Path(scratch).resolve()
+        self.destination = Path(destination)
+        self.count = 0
+        self.total = 0
+        self._result_key = None
+        self._result_key_id = None
+        self._invocation_id = None
+
+    def add(self, *, path, filename, media_type):
+        source = Path(path)
+        if source.is_symlink() or not source.resolve().is_relative_to(self.scratch):
+            raise ValueError("Artifact must be a regular file within scratch space")
+        if not filename or Path(filename).name != filename or any(c in filename for c in "\\\r\n"):
+            raise ValueError("Invalid artifact filename")
+        if not media_type or any(c in media_type for c in "\r\n"):
+            raise ValueError("Invalid media type")
+        if self.count >= 16:
+            raise ValueError("Artifact count exceeds 16")
+        import stat
+        fd = os.open(source, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(fd, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                raise ValueError("Artifact must be a regular file")
+            data = stream.read((16 << 20) + 1)
+        if len(data) > 16 << 20 or self.total + len(data) > 64 << 20:
+            raise ValueError("Artifact size exceeds local limit")
+        self.destination.mkdir(parents=True, exist_ok=True)
+        identifier = str(uuid4())
+        target = self.destination / identifier
+        staged = data
+        if self._result_key:
+            import base64
+            import json
+            from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+            from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+            from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+            ephemeral = X25519PrivateKey.generate()
+            shared = ephemeral.exchange(X25519PublicKey.from_public_bytes(base64.b64decode(self._result_key)))
+            nonce = os.urandom(12)
+            ciphertext = AESGCM(hashlib.sha256(shared).digest()).encrypt(nonce, data, (self._invocation_id + '/' + identifier).encode())
+            staged = json.dumps({'key': base64.b64encode(ephemeral.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)).decode(),
+                                 'key_id': self._result_key_id, 'nonce': base64.b64encode(nonce).decode(), 'sealed': base64.b64encode(ciphertext).decode()}).encode()
+        with target.open("xb") as stream:
+            stream.write(staged)
+        self.count += 1
+        self.total += len(data)
+        return Artifact(id=identifier, filename=filename, media_type=media_type,
+                        size=len(data), sha256=hashlib.sha256(data).hexdigest())

apagea-2026.10.1rc2/apagea/actions/build.py

@@ -0,0 +1,45 @@
+"""Build-time Action interface discovery; never imported by deployed execution."""
+import json
+import os
+from pathlib import Path
+import sys
+
+from apagea.contracts import validate as validate_contract
+from .contract import validate_handler, context_type
+from .runtime import VERSION, MANIFEST, load_handler
+
+
+def build(source, manifest_path=None):
+    import importlib.metadata
+    import tomllib
+    from packaging.specifiers import SpecifierSet
+    manifest_path = manifest_path or MANIFEST
+    config = tomllib.loads((Path(source) / "pyproject.toml").read_text())
+    project = config["project"]
+    if sys.version_info[:2] != (3, 14) or not SpecifierSet(project["requires-python"]).contains(".".join(map(str, sys.version_info[:3]))):
+        raise ValueError("Action requires-python must permit the supplied Python 3.14 interpreter")
+    entry = project["entry-points"]["apagea.action"]
+    if list(entry) != ["handler"]:
+        raise ValueError("Exactly one apagea.action handler entry point is required")
+    handler = load_handler(entry["handler"])
+    input_type, output_type = validate_handler(handler)
+    metadata = config.get("tool", {}).get("apagea", {})
+    from apagea.fields import schema_for
+    manifest = {"version": VERSION, "name": project["name"], "action_version": project["version"],
+                "description": project.get("description", ""), "handler": entry["handler"],
+                "platform": os.environ["ACTION_PLATFORM"], "python": sys.version.split()[0],
+                "sdk_version": importlib.metadata.version("apagea"),
+                "base_image": os.environ["ACTION_BASE"],
+                "network_required": metadata.get("network_required", False),
+                "title": metadata.get("title", project["name"].replace("-", " ").title()),
+                "submit_label": metadata.get("submit-label", "Invoke"),
+                "context_schema": schema_for(context_type(handler)),
+                "timeout_seconds": metadata.get("timeout_seconds", 60),
+                "input_schema": schema_for(input_type), "output_schema": schema_for(output_type, mode="serialization")}
+    validate_contract("action/v1/manifest", manifest)
+    raw = json.dumps(manifest, sort_keys=True, separators=(",", ":"), allow_nan=False)
+    if len(raw.encode()) > 128 << 10:
+        raise ValueError("Action manifest exceeds 128 KiB")
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(raw)
+

apagea-2026.10.1rc2/apagea/actions/build_dependencies.py

@@ -0,0 +1,35 @@
+"""Render validated requirements; the Dockerfile owns package installation."""
+from pathlib import Path
+import sys
+import tomllib
+from packaging.requirements import InvalidRequirement, Requirement
+
+
+def requirements(path, *, build_only=False):
+    metadata = tomllib.loads(Path(path).read_text())
+    requirements = [*metadata.get('build-system', {}).get('requires', []),
+                    *([] if build_only else metadata['project'].get('dependencies', []))]
+    # Parse PEP 508 requirements before writing the pip requirements file. Dynamic project
+    # dependencies are resolved later when the complete source is installed.
+    for value in requirements:
+        if "\n" in value or "\r" in value:
+            raise InvalidRequirement("Requirements must occupy a single line")
+        Requirement(value)
+    return "\n".join(requirements) + ("\n" if requirements else "")
+
+
+def installed_constraints():
+    """Freeze the installed target environment after the hashed lock install.
+
+    Build-system installation must not upgrade either runtime pins or the selected
+    locked dependencies. No second lock export or custom lock parser is needed.
+    """
+    from importlib.metadata import distributions
+    return "\n".join(sorted(f"{d.metadata['Name']}=={d.version}" for d in distributions())) + "\n"
+
+
+if __name__ == '__main__':
+    if sys.argv[1] == '--constraints':
+        sys.stdout.write(installed_constraints())
+    else:
+        sys.stdout.write(requirements(sys.argv[1], build_only='--build-only' in sys.argv[2:]))

apagea-2026.10.1rc2/apagea/actions/contract.py

@@ -0,0 +1,278 @@
+"""Typed handler validation adapted from the Pyplines Action SDK.
+
+Typed Context requirements describe dependencies; scheduling and approval remain server responsibilities.
+"""
+import inspect
+import json
+import sys
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import get_type_hints
+
+from .timing import measure
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr, SecretStr
+
+
+class Inputs(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, hide_input_in_errors=True)
+
+
+class Outputs(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, hide_input_in_errors=True)
+
+
+class ActionError(Exception):
+    """An intentionally public failure; authors MUST omit credentials and secrets."""
+    def __init__(self, message: str, code: str = "action_failed", *, hint: str = ""):
+        self.message = message[:1024]
+        self.code = code[:64]
+        self.hint = hint[:1024]
+        super().__init__(self.message)
+
+
+def _log_json(value):
+    # Match transport escaping so SDK and server enforce the same byte limits.
+    encoded = json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+    for character in ("<", ">", "&", "\u2028", "\u2029"):
+        encoded = encoded.replace(character, "\\u%04x" % ord(character))
+    return encoded
+
+
+class Logger:
+    """Bounded structured logging. Public methods have no aliases."""
+    def __init__(self, invocation_id, stream, secrets=()):
+        self.invocation_id = invocation_id
+        self._stream = stream
+        self._sequence = 0
+        self._lock = threading.Lock()
+        self._secrets = tuple(sorted(set(s for s in secrets if s), key=len, reverse=True))
+
+    def _redact(self, value):
+        if isinstance(value, SecretStr):
+            return "**********"
+        if isinstance(value, dict):
+            return {self._redact(k): self._redact(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [self._redact(v) for v in value]
+        if isinstance(value, str):
+            for secret in self._secrets:
+                value = value.replace(secret, "**********")
+        return value
+
+    def debug(self, message, **fields):
+        self._emit(message, level="debug", **fields)
+
+    def info(self, message, **fields):
+        self._emit(message, level="info", **fields)
+
+    def warn(self, message, **fields):
+        self._emit(message, level="warning", **fields)
+
+    def error(self, message, **fields):
+        self._emit(message, level="error", **fields)
+
+    def exception(self, message, **fields):
+        import traceback
+        fields["exception"] = traceback.format_exc()[-4096:]
+        self._emit(message, level="error", **fields)
+
+    def _emit(self, message: str, stream: str = "stdout", *, level: str = "info", **fields) -> None:
+        """Emit one bounded JSON record. Wrapped and known secret values are masked."""
+        if level not in ("debug", "info", "warning", "error"):
+            raise ValueError("Log level must be debug, info, warning, or error")
+        if stream not in ("stdout", "stderr"):
+            raise ValueError("Log stream must be stdout or stderr")
+        if not isinstance(message, str) or len(message) > 4096:
+            raise ValueError("Log message must be a string of at most 4096 characters")
+        fields = self._redact(fields)
+        for secret in self._secrets:
+            message = message.replace(secret, "**********")
+        def check(value):
+            if isinstance(value, dict):
+                if any(not isinstance(key, str) for key in value):
+                    raise ValueError("Log field keys must be strings")
+                for item in value.values():
+                    check(item)
+            elif isinstance(value, list):
+                for item in value:
+                    check(item)
+            elif value is not None and not isinstance(value, (str, bool, int, float)):
+                raise ValueError("Log fields must contain JSON-compatible values")
+        try:
+            check(fields)
+            encoded_fields = _log_json(fields)
+            if len(encoded_fields.encode()) > 8192:
+                raise ValueError("Log fields exceed 8 KiB")
+        except (TypeError, OverflowError, RecursionError):
+            raise ValueError("Log fields must contain finite JSON-compatible values") from None
+        with self._lock:
+            record = {"sequence": self._sequence + 1,
+                      "invocation_id": self.invocation_id,
+                      "timestamp": datetime.now(timezone.utc).isoformat(),
+                      "stream": stream, "level": level, "message": message}
+            if fields:
+                record["fields"] = fields
+            encoded = _log_json(record)
+            if len(encoded.encode()) > 16384:
+                raise ValueError("Log record exceeds 16 KiB")
+            self._stream.write(encoded + "\n")
+            self._stream.flush()
+            self._sequence += 1
+
+
+
+def secret_values(value):
+    if isinstance(value, SecretStr):
+        return [value.get_secret_value()]
+    if isinstance(value, BaseModel):
+        return secret_values(value.__dict__)
+    if isinstance(value, dict):
+        return [s for v in value.values() for s in secret_values(v)]
+    if isinstance(value, (tuple, list)):
+        return [s for v in value for s in secret_values(v)]
+    return []
+
+
+class Context(BaseModel):
+    """Typed deployment-scoped Context requirements plus runtime facilities (not schema fields)."""
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True, hide_input_in_errors=True)
+    _invocation_id: str = PrivateAttr()
+    _scratch_dir: Path = PrivateAttr()
+    _logger: Logger = PrivateAttr()
+    _artifacts: object = PrivateAttr()
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs):
+        super().__pydantic_init_subclass__(**kwargs)
+        reserved = {"invocation_id", "scratch_dir", "log", "artifacts", "stream", "artifact_dir"}
+        if reserved.intersection(cls.model_fields):
+            raise ValueError("Context fields cannot shadow platform facilities")
+
+    def __init__(self, invocation_id="local", scratch_dir="/tmp", stream=None, *, artifact_dir=None, **values):
+        super().__init__(**values)
+        self._invocation_id = invocation_id
+        self._scratch_dir = Path(scratch_dir)
+        self._logger = Logger(invocation_id, stream if stream is not None else sys.stdout, secret_values(self))
+        from .artifacts import ArtifactStore
+        self._artifacts = ArtifactStore(self._scratch_dir, Path(artifact_dir) if artifact_dir else self._scratch_dir / "artifacts")
+
+    @property
+    def invocation_id(self):
+        return self._invocation_id
+
+    @property
+    def scratch_dir(self):
+        return self._scratch_dir
+
+    @property
+    def log(self):
+        return self._logger
+
+    @property
+    def artifacts(self):
+        return self._artifacts
+
+
+def context_type(handler):
+    params = list(inspect.signature(handler).parameters.values())
+    return get_type_hints(handler)[params[1].name]
+
+def validate_handler(handler):
+    """Require a synchronous (Inputs, Context) -> Outputs function."""
+    if not callable(handler) or inspect.iscoroutinefunction(handler) or inspect.isgeneratorfunction(handler):
+        raise ValueError("Action handler must be a synchronous function")
+    params = list(inspect.signature(handler).parameters.values())
+    if len(params) != 2 or any(p.kind not in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD) for p in params):
+        raise ValueError("Action handler must accept exactly (inputs, context)")
+    try:
+        hints = get_type_hints(handler)
+    except Exception:
+        raise ValueError("Unable to resolve Action type annotations") from None
+    input_type, output_type = hints.get(params[0].name), hints.get("return")
+    if not isinstance(input_type, type) or not issubclass(input_type, Inputs) or input_type is Inputs:
+        raise ValueError("First parameter must be an Inputs subclass")
+    if not isinstance(hints.get(params[1].name), type) or not issubclass(hints[params[1].name], Context):
+        raise ValueError("Second parameter must be a Context subclass")
+    if output_type is type(None):
+        return input_type, Outputs
+    if not isinstance(output_type, type) or not issubclass(output_type, Outputs) or output_type is Outputs:
+        raise ValueError("Return annotation must be an Outputs subclass")
+    return input_type, output_type
+
+
+def execute(handler, payload, context, *, private=False, timings=None):
+    with measure(timings, "handler_validation_ms"):
+        input_type, output_type = validate_handler(handler)
+    try:
+        with measure(timings, "input_validation_ms"):
+            value = input_type.model_validate_json(json.dumps(payload, allow_nan=False), strict=True)
+    except Exception as exc:
+        raise ActionError("Inputs does not satisfy the Action schema", "invalid_input") from exc
+    context.log._secrets = tuple(sorted(set(context.log._secrets + tuple(secret_values(value))), key=len, reverse=True))
+    with measure(timings, "handler_ms"):
+        result = handler(value, context)
+    if output_type is Outputs:
+        if result is not None:
+            raise ActionError("Handler annotated None returned a value", "invalid_output")
+        return {}
+    if not isinstance(result, output_type):
+        raise ActionError("Handler returned an invalid output type", "invalid_output")
+    try:
+        with measure(timings, "output_validation_ms"):
+            # Revalidate constructed/mutated model instances as well as normal returns.
+            validated = output_type.model_validate(_model_values(result), strict=True,
+                                                   by_name=True, by_alias=False)
+            output = validated.model_dump(mode="json", by_alias=True, warnings="error")
+            if private:
+                output = _private_values(validated, output)
+            json.dumps(output, allow_nan=False)
+            return output
+    except Exception as exc:
+        raise ActionError("Outputs does not satisfy the Action schema", "invalid_output") from exc
+
+
+def _validation_values(value):
+    """Revalidate actual field values, without serializers or computed properties."""
+    if isinstance(value, BaseModel):
+        data = (_validation_values(value.root) if value.__pydantic_root_model__
+                else _model_values(value))
+        return type(value).model_validate(data, strict=True, by_name=True, by_alias=False)
+    if isinstance(value, dict):
+        return {key: _validation_values(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return type(value)(_validation_values(item) for item in value)
+    return value
+
+
+def _model_values(value):
+    fields = {name: _validation_values(value.__dict__[name])
+              for name in type(value).model_fields if name in value.__dict__}
+    fields.update({key: _validation_values(item)
+                   for key, item in (value.__pydantic_extra__ or {}).items()})
+    return fields
+
+
+def _private_values(value, encoded):
+    """Preserve declared secrets only inside the result that the runtime seals."""
+    if isinstance(value, SecretStr):
+        return value.get_secret_value()
+    if isinstance(value, BaseModel) and value.__pydantic_root_model__:
+        return _private_values(value.root, encoded)
+    if isinstance(value, BaseModel) and isinstance(encoded, dict):
+        for name, field in type(value).model_fields.items():
+            key = field.serialization_alias or field.alias or name
+            if key in encoded:
+                encoded[key] = _private_values(getattr(value, name), encoded[key])
+        for name, field in type(value).model_computed_fields.items():
+            key = field.alias or name
+            if key in encoded:
+                encoded[key] = _private_values(getattr(value, name), encoded[key])
+    elif isinstance(value, dict) and isinstance(encoded, dict):
+        for key, item in value.items():
+            if key in encoded:
+                encoded[key] = _private_values(item, encoded[key])
+    elif isinstance(value, (list, tuple)) and isinstance(encoded, list):
+        encoded = [_private_values(item, val) for item, val in zip(value, encoded)]
+    return encoded