blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/php/src/Errors/BlokErrorCategory.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * The 12 canonical error categories every Blok node error falls into.
+ *
+ * Mirrors the proto `blok.runtime.v1.ErrorCategory` enum value-for-value and
+ * matches the Python `BlokErrorCategory`, Go `CategoryDependency`, Rust
+ * `BlokErrorCategory::Dependency`, Java `BlokErrorCategory.DEPENDENCY`, C#
+ * `BlokErrorCategory.Dependency`, and Ruby `Category::DEPENDENCY` constants.
+ * Each category carries a default HTTP status and retryable hint that authors
+ * can override per-error via the builder.
+ */
+enum BlokErrorCategory: string
+{
+    /** Input failed schema validation. Default HTTP 400, non-retryable. */
+    case Validation = 'VALIDATION';
+    /** Misconfiguration of the runner / node / environment. Default 500, non-retryable. */
+    case Configuration = 'CONFIGURATION';
+    /** External dependency unreachable (DB, API). Default 502, retryable. */
+    case Dependency = 'DEPENDENCY';
+    /** Deadline exceeded. Default 504, retryable. */
+    case Timeout = 'TIMEOUT';
+    /** Caller lacks the right role/scope. Default 403, non-retryable. */
+    case Permission = 'PERMISSION';
+    /** Caller exceeded a quota. Default 429, retryable with retry_after_ms. */
+    case RateLimit = 'RATE_LIMIT';
+    /** Resource not found. Default 404, non-retryable. */
+    case NotFound = 'NOT_FOUND';
+    /** Idempotency violation, concurrent update. Default 409, non-retryable. */
+    case Conflict = 'CONFLICT';
+    /** Caller cancelled before completion. Default 499, non-retryable. */
+    case Cancelled = 'CANCELLED';
+    /** SDK threw without classification — default fallback. Default 500, non-retryable. */
+    case Internal = 'INTERNAL';
+    /** Wire-format / framing / serialization error. Default 502, non-retryable. */
+    case Protocol = 'PROTOCOL';
+    /** Payload schema OK but values are unprocessable. Default 422, non-retryable. */
+    case Data = 'DATA';
+
+    /** HTTP status conventionally associated with this category. */
+    public function defaultHttpStatus(): int
+    {
+        return match ($this) {
+            self::Validation => 400,
+            self::Configuration => 500,
+            self::Dependency => 502,
+            self::Timeout => 504,
+            self::Permission => 403,
+            self::RateLimit => 429,
+            self::NotFound => 404,
+            self::Conflict => 409,
+            self::Cancelled => 499,
+            self::Internal => 500,
+            self::Protocol => 502,
+            self::Data => 422,
+        };
+    }
+
+    /** Retryable hint conventionally associated with this category. */
+    public function defaultRetryable(): bool
+    {
+        return match ($this) {
+            self::Dependency, self::Timeout, self::RateLimit => true,
+            default => false,
+        };
+    }
+
+    /**
+     * Parse a wire string into a category, falling back to {@see self::Internal}
+     * for unknown values (matches Python/Go/Rust/Java/C#/Ruby behaviour).
+     */
+    public static function parse(?string $value): self
+    {
+        if ($value === null) {
+            return self::Internal;
+        }
+        return self::tryFrom($value) ?? self::Internal;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Errors/BlokErrorSeverity.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * How serious an error is. Mirrors the proto `blok.runtime.v1.ErrorSeverity`
+ * enum. Default for thrown errors is {@see self::Error}.
+ */
+enum BlokErrorSeverity: string
+{
+    /** Informational, no action needed. */
+    case Info = 'INFO';
+    /** Recoverable, worth surfacing. */
+    case Warn = 'WARN';
+    /** Standard error level. */
+    case Error = 'ERROR';
+    /** Process must terminate. */
+    case Fatal = 'FATAL';
+
+    /** Parse a wire string, falling back to {@see self::Error}. */
+    public static function parse(?string $value): self
+    {
+        if ($value === null) {
+            return self::Error;
+        }
+        return self::tryFrom($value) ?? self::Error;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Errors/BuildContextSnapshot.php

@@ -0,0 +1,141 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * Bounded slice of inputs + recent vars for the
+ * `BlokError->contextSnapshot` field, per master plan §17.6.
+ *
+ * Default budget: 4 KB serialized + last-16 vars keys, with progressive
+ * trimming when oversize. `inputs` is preserved as-is — it's the most
+ * LLM-actionable context. Mirrors Python's `build_context_snapshot`, Go's
+ * `BuildContextSnapshot`, Rust's `build_context_snapshot`, Java's
+ * `BuildContextSnapshot.of`, C#'s `BuildContextSnapshot.Of`, and Ruby's
+ * `BuildContextSnapshot.of`.
+ */
+final class BuildContextSnapshot
+{
+    /**
+     * Snapshot of `inputs` + last-16 vars keys, capped at 4 KB.
+     *
+     * @param array<string, mixed> $inputs
+     * @param array<string, mixed> $vars
+     * @return array<string, mixed>
+     */
+    public static function of(array $inputs, array $vars): array
+    {
+        return self::withOpts($inputs, $vars, BlokError::CONTEXT_SNAPSHOT_MAX_BYTES, 16);
+    }
+
+    /**
+     * Customizable variant. `$maxVarsKeys = 0` drops vars entirely.
+     * `$maxBytes <= 0` disables byte-budget trimming.
+     *
+     * @param array<string, mixed> $inputs
+     * @param array<string, mixed> $vars
+     * @return array<string, mixed>
+     */
+    public static function withOpts(array $inputs, array $vars, int $maxBytes, int $maxVarsKeys): array
+    {
+        $safeInputs = self::jsonSafeMap($inputs);
+
+        // ksort gives a deterministic "last N" slice. PHP arrays preserve
+        // insertion order, but tests need cross-runtime determinism;
+        // mirroring Java's TreeMap, Rust's BTreeMap, C#'s SortedDictionary,
+        // and Ruby's sorted-keys.
+        ksort($vars);
+        $keys = array_keys($vars);
+        if ($maxVarsKeys >= 0 && count($keys) > $maxVarsKeys) {
+            $keys = array_slice($keys, count($keys) - $maxVarsKeys);
+        }
+
+        $snapshot = [
+            'inputs' => $safeInputs,
+            'vars'   => self::buildRecent($vars, $keys),
+        ];
+
+        if ($maxBytes <= 0) {
+            return $snapshot;
+        }
+
+        if (self::encodedBytes($snapshot) <= $maxBytes) {
+            return $snapshot;
+        }
+
+        // Trim from the front (oldest keys) until the snapshot fits.
+        while (!empty($keys)) {
+            array_shift($keys);
+            $snapshot['vars'] = self::buildRecent($vars, $keys);
+            if (self::encodedBytes($snapshot) <= $maxBytes) {
+                return $snapshot;
+            }
+        }
+
+        return [
+            'inputs'      => $safeInputs,
+            'vars'        => [],
+            '_truncated'  => true,
+        ];
+    }
+
+    /**
+     * @param array<string, mixed> $vars
+     * @param array<int, string>   $keys
+     * @return array<string, mixed>
+     */
+    private static function buildRecent(array $vars, array $keys): array
+    {
+        $recent = [];
+        foreach ($keys as $k) {
+            if (array_key_exists($k, $vars)) {
+                $recent[$k] = self::jsonSafe($vars[$k]);
+            }
+        }
+        return $recent;
+    }
+
+    private static function encodedBytes(mixed $value): int
+    {
+        $json = json_encode($value, JSON_UNESCAPED_SLASHES);
+        if ($json === false) {
+            return PHP_INT_MAX;
+        }
+        return strlen($json);
+    }
+
+    /**
+     * @param array<string, mixed> $m
+     * @return array<string, mixed>
+     */
+    private static function jsonSafeMap(array $m): array
+    {
+        $out = [];
+        foreach ($m as $k => $v) {
+            $out[(string) $k] = self::jsonSafe($v);
+        }
+        return $out;
+    }
+
+    private static function jsonSafe(mixed $v): mixed
+    {
+        if (is_scalar($v) || $v === null) {
+            return $v;
+        }
+        if (is_array($v)) {
+            // Arrays may be associative or list — preserve as-is.
+            $out = [];
+            foreach ($v as $k => $val) {
+                $out[is_int($k) ? $k : (string) $k] = self::jsonSafe($val);
+            }
+            return $out;
+        }
+        // Try JSON round-trip; fall back to a string repr.
+        $json = json_encode($v, JSON_UNESCAPED_SLASHES);
+        if ($json !== false) {
+            return json_decode($json, true);
+        }
+        return is_object($v) ? $v::class : 'unserializable';
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Errors/ErrorCategory.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * ErrorCategory classifies the type of error that occurred.
+ */
+enum ErrorCategory: string
+{
+    case Validation = 'VALIDATION';
+    case Execution = 'EXECUTION';
+    case Configuration = 'CONFIGURATION';
+    case Network = 'NETWORK';
+    case NotFound = 'NOT_FOUND';
+}

package/dist/scaffold-repo/sdks/php/src/Errors/NodeException.php

@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * NodeException represents a structured error from node execution.
+ *
+ * Provides static factory methods for common error categories.
+ */
+final class NodeException extends \Exception
+{
+    public function __construct(
+        string $message,
+        private readonly int $errorCode,
+        private readonly ErrorCategory $category,
+        private readonly mixed $details = null,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf('[%s] %s', $this->category->value, $message),
+            $this->errorCode,
+            $previous,
+        );
+    }
+
+    /**
+     * Get the error code.
+     */
+    public function getErrorCode(): int
+    {
+        return $this->errorCode;
+    }
+
+    /**
+     * Get the error category.
+     */
+    public function getCategory(): ErrorCategory
+    {
+        return $this->category;
+    }
+
+    /**
+     * Get the error details.
+     */
+    public function getDetails(): mixed
+    {
+        return $this->details;
+    }
+
+    /**
+     * Create a validation error (400).
+     */
+    public static function validation(string $message, mixed $details = null): self
+    {
+        return new self($message, 400, ErrorCategory::Validation, $details);
+    }
+
+    /**
+     * Create an execution error (500).
+     */
+    public static function execution(string $message, mixed $details = null): self
+    {
+        return new self($message, 500, ErrorCategory::Execution, $details);
+    }
+
+    /**
+     * Create a configuration error (500).
+     */
+    public static function configuration(string $message, mixed $details = null): self
+    {
+        return new self($message, 500, ErrorCategory::Configuration, $details);
+    }
+
+    /**
+     * Create a network error (502).
+     */
+    public static function network(string $message, mixed $details = null): self
+    {
+        return new self($message, 502, ErrorCategory::Network, $details);
+    }
+
+    /**
+     * Create a not-found error (404).
+     */
+    public static function notFound(string $message, mixed $details = null): self
+    {
+        return new self($message, 404, ErrorCategory::NotFound, $details);
+    }
+
+    /**
+     * Convert to a JSON-compatible array for ExecutionResult.errors.
+     */
+    public function toArray(): array
+    {
+        $result = [
+            'message' => $this->getMessage(),
+            'code' => $this->errorCode,
+            'category' => $this->category->value,
+        ];
+        if ($this->details !== null) {
+            $result['details'] = $this->details;
+        }
+        return $result;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Errors/Origin.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Errors;
+
+/**
+ * Carrier of the auto-enrichment fields the gRPC servicer fills into a
+ * handler-thrown {@see BlokError} when the handler didn't set those fields
+ * explicitly.
+ */
+final class Origin
+{
+    public function __construct(
+        public readonly string $node,
+        public readonly string $sdk,
+        public readonly string $sdkVersion,
+        public readonly string $runtimeKind,
+    ) {}
+
+    /**
+     * Build an {@see Origin} populated with the SDK constants
+     * ({@see BlokError::DEFAULT_SDK_NAME}, {@see BlokError::DEFAULT_RUNTIME_KIND})
+     * and the caller-provided node name + SDK version.
+     */
+    public static function defaults(string $node, string $sdkVersion): self
+    {
+        return new self(
+            node: $node,
+            sdk: BlokError::DEFAULT_SDK_NAME,
+            sdkVersion: $sdkVersion,
+            runtimeKind: BlokError::DEFAULT_RUNTIME_KIND,
+        );
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Genpb/Blok/Runtime/V1/ErrorCategory.php

@@ -0,0 +1,118 @@
+<?php
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: blok/runtime/v1/runtime.proto
+
+namespace Blok\Runtime\V1;
+
+use UnexpectedValueException;
+
+/**
+ * Protobuf type <code>blok.runtime.v1.ErrorCategory</code>
+ */
+class ErrorCategory
+{
+    /**
+     * Generated from protobuf enum <code>CATEGORY_UNSPECIFIED = 0;</code>
+     */
+    const CATEGORY_UNSPECIFIED = 0;
+    /**
+     * input/output schema mismatch
+     *
+     * Generated from protobuf enum <code>VALIDATION = 1;</code>
+     */
+    const VALIDATION = 1;
+    /**
+     * node misconfigured
+     *
+     * Generated from protobuf enum <code>CONFIGURATION = 2;</code>
+     */
+    const CONFIGURATION = 2;
+    /**
+     * external service failed (DB, HTTP, queue)
+     *
+     * Generated from protobuf enum <code>DEPENDENCY = 3;</code>
+     */
+    const DEPENDENCY = 3;
+    /**
+     * Generated from protobuf enum <code>TIMEOUT = 4;</code>
+     */
+    const TIMEOUT = 4;
+    /**
+     * auth/authz
+     *
+     * Generated from protobuf enum <code>PERMISSION = 5;</code>
+     */
+    const PERMISSION = 5;
+    /**
+     * Generated from protobuf enum <code>RATE_LIMIT = 6;</code>
+     */
+    const RATE_LIMIT = 6;
+    /**
+     * Generated from protobuf enum <code>NOT_FOUND = 7;</code>
+     */
+    const NOT_FOUND = 7;
+    /**
+     * Generated from protobuf enum <code>CONFLICT = 8;</code>
+     */
+    const CONFLICT = 8;
+    /**
+     * Generated from protobuf enum <code>CANCELLED = 9;</code>
+     */
+    const CANCELLED = 9;
+    /**
+     * unexpected SDK-side bug
+     *
+     * Generated from protobuf enum <code>INTERNAL = 10;</code>
+     */
+    const INTERNAL = 10;
+    /**
+     * proto/transport issue
+     *
+     * Generated from protobuf enum <code>PROTOCOL = 11;</code>
+     */
+    const PROTOCOL = 11;
+    /**
+     * user data malformed (not schema validation)
+     *
+     * Generated from protobuf enum <code>DATA = 12;</code>
+     */
+    const DATA = 12;
+
+    private static $valueToName = [
+        self::CATEGORY_UNSPECIFIED => 'CATEGORY_UNSPECIFIED',
+        self::VALIDATION => 'VALIDATION',
+        self::CONFIGURATION => 'CONFIGURATION',
+        self::DEPENDENCY => 'DEPENDENCY',
+        self::TIMEOUT => 'TIMEOUT',
+        self::PERMISSION => 'PERMISSION',
+        self::RATE_LIMIT => 'RATE_LIMIT',
+        self::NOT_FOUND => 'NOT_FOUND',
+        self::CONFLICT => 'CONFLICT',
+        self::CANCELLED => 'CANCELLED',
+        self::INTERNAL => 'INTERNAL',
+        self::PROTOCOL => 'PROTOCOL',
+        self::DATA => 'DATA',
+    ];
+
+    public static function name($value)
+    {
+        if (!isset(self::$valueToName[$value])) {
+            throw new UnexpectedValueException(sprintf(
+                    'Enum %s has no name defined for value %s', __CLASS__, $value));
+        }
+        return self::$valueToName[$value];
+    }
+
+
+    public static function value($name)
+    {
+        $const = __CLASS__ . '::' . strtoupper($name);
+        if (!defined($const)) {
+            throw new UnexpectedValueException(sprintf(
+                    'Enum %s has no value defined for name %s', __CLASS__, $name));
+        }
+        return constant($const);
+    }
+}
+

package/dist/scaffold-repo/sdks/php/src/Genpb/Blok/Runtime/V1/ErrorSeverity.php

@@ -0,0 +1,72 @@
+<?php
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: blok/runtime/v1/runtime.proto
+
+namespace Blok\Runtime\V1;
+
+use UnexpectedValueException;
+
+/**
+ * Protobuf type <code>blok.runtime.v1.ErrorSeverity</code>
+ */
+class ErrorSeverity
+{
+    /**
+     * Generated from protobuf enum <code>SEVERITY_UNSPECIFIED = 0;</code>
+     */
+    const SEVERITY_UNSPECIFIED = 0;
+    /**
+     * expected, recoverable
+     *
+     * Generated from protobuf enum <code>INFO = 1;</code>
+     */
+    const INFO = 1;
+    /**
+     * anomalous but workflow continues
+     *
+     * Generated from protobuf enum <code>WARN = 2;</code>
+     */
+    const WARN = 2;
+    /**
+     * node failed; default
+     *
+     * Generated from protobuf enum <code>ERROR = 3;</code>
+     */
+    const ERROR = 3;
+    /**
+     * workflow should abort regardless of try/catch
+     *
+     * Generated from protobuf enum <code>FATAL = 4;</code>
+     */
+    const FATAL = 4;
+
+    private static $valueToName = [
+        self::SEVERITY_UNSPECIFIED => 'SEVERITY_UNSPECIFIED',
+        self::INFO => 'INFO',
+        self::WARN => 'WARN',
+        self::ERROR => 'ERROR',
+        self::FATAL => 'FATAL',
+    ];
+
+    public static function name($value)
+    {
+        if (!isset(self::$valueToName[$value])) {
+            throw new UnexpectedValueException(sprintf(
+                    'Enum %s has no name defined for value %s', __CLASS__, $value));
+        }
+        return self::$valueToName[$value];
+    }
+
+
+    public static function value($name)
+    {
+        $const = __CLASS__ . '::' . strtoupper($name);
+        if (!defined($const)) {
+            throw new UnexpectedValueException(sprintf(
+                    'Enum %s has no value defined for name %s', __CLASS__, $name));
+        }
+        return constant($const);
+    }
+}
+