specfuse-loop 0.27.0__tar.gz → 0.28.0__tar.gz

{specfuse_loop-0.27.0/specfuse_loop.egg-info → specfuse_loop-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.27.0
+Version: 0.28.0
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.27.0"
+version = "0.28.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

specfuse_loop-0.28.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.28.0

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/loop/data/monitoring.yml.example

@@ -81,6 +81,15 @@ components:
       # Use for any component that serves HTTP traffic directly.
       - type: http-5xx
 
+      # http-status-regression: alerts when a deployment raises the rate of
+      # server-fault 4xx responses compared with the window before it.
+      - type: http-status-regression
+        deploy_signal:
+          kind: app-version
+        window_after_deploy: 1h
+        # codes defaults to [403, 405, 415]; this one also opts in to 401.
+        codes: [401, 403, 405, 415]
+
       # heartbeat: alerts when the component stops reporting in at all —
       # the check that catches "it didn't error, it just went silent."
       - type: heartbeat

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/loop/data/rules/design-for-diagnosis.md

@@ -7,8 +7,8 @@ Licensed under the Apache License, Version 2.0. See LICENSE.
 
 This rule governs the *target application's* code — not this loop's own
 execution. It states what a deployed component must do so the check types a
-`monitoring.yml` admits (`dlq`, `error-logs`, `http-5xx`, `heartbeat`,
-`invariant`) produce a diagnosable finding instead of a bare alert. A check that
+`monitoring.yml` admits (`dlq`, `error-logs`, `http-5xx`,
+`http-status-regression`, `heartbeat`, `invariant`, `queue-stalled`) produce a diagnosable finding instead of a bare alert. A check that
 fires without one of these properties tells an operator only that something is
 wrong, not what or where.
 
@@ -74,6 +74,26 @@ log destination must each stamp their own role name on every record; a shared,
 unstamped log stream makes the two indistinguishable once findings are
 harvested.
 
+## Scheduled work emits one heartbeat event per firing
+
+A component that runs work on a schedule emits a heartbeat each time a schedule
+fires, in exactly this shape: one custom event named `ScheduleHeartbeat`,
+carrying the schedule's name in a property named `scheduleName`, emitted under
+the component's role name (the same role name the previous section requires,
+matching the `monitoring.yml` entry). The `scheduleName` value is the same
+string as the `name` of the matching `heartbeat` target in `monitoring.yml`.
+Emit once per firing — not once per item processed, and not only on success
+paths that may never be reached.
+
+A `heartbeat` check finds a silent schedule by the *absence* of this event: it
+computes when each target's schedule last should have fired and looks for a
+`ScheduleHeartbeat` event with that target's `scheduleName`, under that role
+name, at or after that time. A component that emits nothing, emits under a
+different event name or property, or emits without its role name is
+indistinguishable from one whose schedule has stopped — the check reports every
+target as silent from its first run, and the real silence, when it comes, is
+lost in that noise.
+
 ## DLQ entries carry failure context, not just the payload
 
 A message that lands in a dead-letter queue carries, alongside its original
@@ -88,3 +108,17 @@ an operator has to reproduce the failure from scratch, from a payload alone,
 with no error, no attempt count, and no correlation ID to trace back to the
 request that produced it. Context captured at dead-letter time is the
 difference between a diagnosis and a re-investigation.
+
+## A deployable stamps a version that changes on every deployment
+
+An HTTP-serving component stamps a service version onto the telemetry it emits,
+and that version changes on every deployment — the stamp is injected at build or
+release time, not a constant in source that survives a release unchanged.
+
+An `http-status-regression` check detects a deployment by the first appearance
+of a new version value, then compares the failure rate of newly-seen client-error
+and server-error statuses after that point with the rate before it. A component
+that stamps no version has no deployment signal at all; one that stamps the same
+value every release shows no new version to detect, so the check never opens its
+post-deployment window and a regression ships unseen. Either way the check
+cannot be evaluated, and discovery reports the gap rather than proposing it.

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/loop/lint_monitoring.py

@@ -35,6 +35,8 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
+from specfuse.monitor.durations import DURATION_GRAMMAR, parse_duration_seconds
+
 from . import _miniyaml
 
 __all__ = ("validate_monitoring", "main", "CRON_DIALECTS")
@@ -43,7 +45,15 @@ RUNNER_VALUES = frozenset({"local", "gh-actions", "in-cluster"})
 DIAGNOSE_VALUES = frozenset({"manual", "auto"})
 AUTOFIX_VALUES = frozenset({"off", "on"})
 CHECK_TYPES = frozenset(
-    {"dlq", "error-logs", "http-5xx", "heartbeat", "invariant", "queue-stalled"}
+    {
+        "dlq",
+        "error-logs",
+        "http-5xx",
+        "http-status-regression",
+        "heartbeat",
+        "invariant",
+        "queue-stalled",
+    }
 )
 HARVEST_MODE_VALUES = frozenset({"peek", "quarantine"})
 
@@ -250,6 +260,8 @@ def _check_checks(checks: object, component_label: str) -> list[str]:
                     f"'queue-stalled' check requires 'targets' — each target "
                     f"needs 'subscription' and 'function'"
                 )
+        elif check_type == "http-status-regression":
+            findings.extend(_check_http_status_regression(check, component_label, index))
         elif check_type == "invariant":
             for field in ("query", "fingerprint_by"):
                 if not check.get(field):
@@ -274,8 +286,63 @@ _TARGET_REQUIRED_FIELDS = {
     "heartbeat": ("name",),
     "queue-stalled": ("subscription", "function"),
 }
+DEPLOY_SIGNAL_KINDS = frozenset({"app-version"})
+
+
+def _check_http_status_regression(
+    check: dict, component_label: str, check_index: int
+) -> list[str]:
+    """Field rules for one `http-status-regression` check (`targets` is
+    rejected by `_check_targets`)."""
+    where = f"component '{component_label}': checks[{check_index}]"
+    prefix = f"{where}: 'http-status-regression' check"
+    findings: list[str] = []
+
+    signal = check.get("deploy_signal")
+    if not isinstance(signal, dict) or not signal.get("kind"):
+        findings.append(
+            f"{prefix} requires 'deploy_signal' — a mapping with a 'kind'"
+        )
+    elif signal["kind"] not in DEPLOY_SIGNAL_KINDS:
+        findings.append(
+            f"{prefix} has unknown 'deploy_signal' kind {signal['kind']!r} — "
+            f"must be one of {sorted(DEPLOY_SIGNAL_KINDS)}"
+        )
+
+    window = check.get("window_after_deploy")
+    if window is None:
+        findings.append(f"{prefix} requires 'window_after_deploy'")
+    else:
+        try:
+            parse_duration_seconds(str(window))
+        except ValueError:
+            findings.append(
+                f"{prefix} 'window_after_deploy' value {window!r} is not a "
+                f"valid duration — expected {DURATION_GRAMMAR}"
+            )
+
+    codes = check.get("codes")
+    if codes is not None:
+        if (
+            not isinstance(codes, list)
+            or not codes
+            or not all(
+                isinstance(c, int) and not isinstance(c, bool) and 400 <= c <= 499
+                for c in codes
+            )
+        ):
+            findings.append(
+                f"{prefix} 'codes' must be a non-empty list of integers in 400–499"
+            )
+        elif len(set(codes)) != len(codes):
+            findings.append(f"{prefix} 'codes' must not contain duplicates")
+    return findings
+
+
 # Check types that must never carry `targets` at all.
-_TARGETLESS_CHECK_TYPES = frozenset({"error-logs", "http-5xx", "invariant"})
+_TARGETLESS_CHECK_TYPES = frozenset(
+    {"error-logs", "http-5xx", "http-status-regression", "invariant"}
+)
 
 
 def _check_targets(
@@ -329,6 +396,15 @@ def _check_targets(
                 )
         if check_type == "heartbeat":
             findings.extend(_check_cron_dialect(target, where, t_index))
+        if check_type == "queue-stalled" and target.get("stall_after") is not None:
+            try:
+                parse_duration_seconds(str(target["stall_after"]))
+            except ValueError:
+                findings.append(
+                    f"{where}: targets[{t_index}]: 'queue-stalled' target "
+                    f"'stall_after' value {target['stall_after']!r} is not a "
+                    f"valid duration — expected {DURATION_GRAMMAR}"
+                )
     return findings
 
 

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/loop/loop.py

@@ -127,7 +127,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.27.0"
+DRIVER_VERSION = "0.28.0"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/monitor/artifact.py

@@ -31,7 +31,9 @@ _TARGET_COORDINATE_FIELDS: Mapping[str, tuple[str, ...]] = {
 
 # Check types that must never carry target coordinates — 0069 rejected
 # `targets` on these, so `fingerprint_by` stays their single enumeration key.
-_TARGETLESS_CHECK_TYPES = frozenset({"error-logs", "http-5xx", "invariant"})
+_TARGETLESS_CHECK_TYPES = frozenset(
+    {"error-logs", "http-5xx", "http-status-regression", "invariant"}
+)
 
 
 @dataclass(frozen=True)

{specfuse_loop-0.27.0 → specfuse_loop-0.28.0}/specfuse/monitor/cli.py

@@ -252,6 +252,9 @@ def _build_adapter(cls, *, component: str, environment: Mapping[str, object], ch
         query=check.get("query"),
         fingerprint_by=check.get("fingerprint_by"),
         max_message_count=check.get("max_message_count", 50),
+        deploy_signal=check.get("deploy_signal"),
+        window_after_deploy=check.get("window_after_deploy"),
+        codes=check.get("codes"),
     )
     return _call_filtered(cls, **kwargs)
 

specfuse_loop-0.28.0/specfuse/monitor/durations.py

@@ -0,0 +1,40 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""The `<integer><unit>` duration grammar, one home for adapter and linter.
+
+Imports nothing from any provider SDK: `specfuse.loop` (the linter) imports
+this module, and the linter must stay SDK-free.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Mapping
+
+DURATION_GRAMMAR = "<integer><unit> with unit in s/m/h/d, e.g. '15m'"
+
+_DURATION_RE = re.compile(r"^(\d+)([smhd])$")
+_DURATION_MULTIPLIERS: Mapping[str, int] = {
+    "s": 1,
+    "m": 60,
+    "h": 3600,
+    "d": 86400,
+}
+
+
+def parse_duration_seconds(value: str, field: str = "stall_after") -> int:
+    """Parse `<integer><unit>` (unit in s/m/h/d) into seconds.
+
+    Refuses rather than guesses: anything outside the grammar — no unit, an
+    unsupported unit, whitespace, a negative sign — raises `ValueError`
+    naming the offending value. No coercion, no silent zero.
+    """
+    match = _DURATION_RE.match(value) if isinstance(value, str) else None
+    if not match:
+        raise ValueError(
+            f"invalid {field} value {value!r} — expected {DURATION_GRAMMAR}"
+        )
+    magnitude, unit = match.groups()
+    return int(magnitude) * _DURATION_MULTIPLIERS[unit]