Code

/* Ring buffer — fixed capacity, no allocation after init. */
#include <stdint.h>
#define RING_CAP 256          // macro: a decorator-role token

typedef enum { RING_OK = 0, RING_FULL = 1 } ring_status_t;

typedef struct {
    uint8_t  data[RING_CAP];
    size_t   head, tail;
    _Bool    wrapped;
} ring_t;

static inline size_t ring_len(const ring_t *r) {
    return (r->head - r->tail) & (RING_CAP - 1);
}

static const char *RING_TAG = "ring\n";   // string literal

ring_status_t ring_push(ring_t *restrict r, uint8_t byte) {
    // Reject when one slot short of capacity, so head never meets tail.
    if (ring_len(r) == RING_CAP - 1) return RING_FULL;
    r->data[r->head++ & (RING_CAP - 1)] = byte;
    return RING_OK;
}

// Policy-based cache. Types, templates, and a lambda.
#include <string>
#include <unordered_map>

namespace projectious::cache {

template <typename Key, typename Value>
class LruCache final {
public:
    explicit LruCache(std::size_t capacity) noexcept : capacity_{capacity} {}

    [[nodiscard]] auto get(const Key& key) const -> const Value* {
        const auto it = entries_.find(key);
        return it == entries_.end() ? nullptr : &it->second;
    }

    void put(Key key, Value value) {
        static constexpr auto kTag = "lru";  // string literal
        // Evict before insert so size never exceeds the capacity.
        if (entries_.size() >= capacity_) evict();
        entries_.emplace(std::move(key), std::move(value));
    }

private:
    void evict() noexcept { /* … */ }

    std::size_t capacity_{0};
    std::unordered_map<Key, Value> entries_{};
};

}  // namespace projectious::cache

"""Pipeline stages and their policy gates."""

from __future__ import annotations

import functools
from dataclasses import dataclass, field
from typing import Final, Iterable

# Retry budget is a policy decision, not a tuning knob.
MAX_RETRIES: Final[int] = 3
DEFAULT_POLICY = "strict"


@dataclass(frozen=True, slots=True)
class Stage:
    """A single stage. Immutable once constructed."""

    name: str
    policy: str = DEFAULT_POLICY
    retries: int = 0
    tags: list[str] = field(default_factory=list)

    @property
    def is_strict(self) -> bool:
        return self.policy == "strict"

    @staticmethod
    def parse(raw: str) -> "Stage":
        name, _, policy = raw.partition(":")
        return Stage(name=name.strip(), policy=policy or DEFAULT_POLICY)


@functools.lru_cache(maxsize=None)
def validate(stages: Iterable[Stage]) -> bool:
    for stage in stages:
        if stage.retries > MAX_RETRIES:
            raise ValueError(f"{stage.name!r} exceeds {MAX_RETRIES} retries")
    return True

//! Policy evaluation for pipeline stages.

use std::collections::HashMap;
use std::fmt::{self, Display};

const MAX_RETRIES: u32 = 3;

/// How strictly a stage is evaluated.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Policy {
    Strict,
    Advisory,
}

#[derive(Debug, Default)]
pub struct Stage<'a> {
    pub name: &'a str,
    pub policy: Option<Policy>,
    pub retries: u32,
}

impl<'a> Stage<'a> {
    // Strict by default: a gate that is not configured should fail closed.
    pub fn new(name: &'a str) -> Self {
        Self { name, policy: Some(Policy::Strict), retries: 0 }
    }

    pub fn validate(&self) -> Result<(), String> {
        if self.retries > MAX_RETRIES {
            return Err(format!("{} exceeds {MAX_RETRIES} retries", self.name));
        }
        Ok(())
    }
}

impl Display for Policy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", match self { Policy::Strict => "strict", _ => "advisory" })
    }
}

// Package pipeline evaluates stages against their policy gates.
package pipeline

import (
	"errors"
	"fmt"
)

const MaxRetries = 3

// Policy is how strictly a stage is evaluated.
type Policy int

const (
	Strict Policy = iota
	Advisory
)

var ErrTooManyRetries = errors.New("stage exceeds retry budget")

type Stage struct {
	Name    string `json:"name"`
	Policy  Policy `json:"policy"`
	Retries int    `json:"retries,omitempty"`
}

func (s *Stage) Validate() error {
	if s.Retries > MaxRetries {
		return fmt.Errorf("%q: %w", s.Name, ErrTooManyRetries)
	}
	return nil
}

func ValidateAll(stages []Stage) (ok bool, err error) {
	for i := range stages {
		if err = stages[i].Validate(); err != nil {
			return false, err
		}
	}
	return true, nil
}

package work.projectious.pipeline;

import java.util.List;
import java.util.Objects;

/** A single pipeline stage and its policy gate. */
public final class Stage implements Comparable<Stage> {

    public static final int MAX_RETRIES = 3;
    public static final long TIMEOUT_MS = 30_000L;
    public static final int MASK = 0xFF;

    private final String name;
    private final Policy policy;
    private int retries = 0;
    private double budget = 12.60;

    public Stage(String name, Policy policy) {
        this.name = Objects.requireNonNull(name, "name");
        this.policy = policy;
    }

    @Override
    public int compareTo(Stage other) {
        return this.name.compareTo(other.name);
    }

    @Deprecated(since = "2.0", forRemoval = true)
    public boolean isStrict() {
        return policy == Policy.STRICT;
    }

    public void validate(List<String> errors) throws IllegalStateException {
        if (retries > MAX_RETRIES) {
            throw new IllegalStateException("%s exceeds %d retries".formatted(name, MAX_RETRIES));
        }
    }

    public enum Policy { STRICT, ADVISORY }
}

; Sum a byte array. rdi = pointer, rsi = length, returns in rax.
        section .data
msg:    db  "sum: ", 0
LEN     equ 5

        section .text
        global  sum_bytes

sum_bytes:
        xor     rax, rax            ; accumulator
        test    rsi, rsi
        jz      .done               ; empty input

.loop:
        movzx   rdx, byte [rdi]
        add     rax, rdx
        inc     rdi
        dec     rsi
        jnz     .loop

.done:
        ret

#!/usr/bin/env bash
# Validate a pipeline definition and promote it when the gates pass.
set -euo pipefail

readonly MAX_RETRIES=3
readonly POLICY="${PIPELINE_POLICY:-strict}"
declare -A GATE_STATUS=()

log() { printf '%s  %s\n' "$(date -u +%FT%TZ)" "$*" >&2; }

validate_stage() {
    local -r name="$1" retries="${2:-0}"
    if (( retries > MAX_RETRIES )); then
        log "ERROR ${name} exceeds ${MAX_RETRIES} retries"
        return 1
    fi
    GATE_STATUS["$name"]="ok"
}

main() {
    local -a stages=("validate" "deploy")
    for stage in "${stages[@]}"; do
        validate_stage "$stage" 0 || exit 1
    done
    log "policy=${POLICY} stages=${#stages[@]}"
}

main "$@"

\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}

% Pipeline notation used throughout the paper.
\newcommand{\stage}[2]{\ensuremath{#1 \xrightarrow{#2}}}

\title{Policy Gates in Composable Pipelines}
\author{Jane Doe}

\begin{document}
\maketitle

\section{Definitions}
A stage $s_i$ passes when its retry count $r_i \leq 3$:
\begin{equation}
    \forall s_i \in S : r_i \leq R_{\max}, \quad R_{\max} = 3
\end{equation}

\begin{itemize}
    \item \textbf{Strict} — the gate fails closed.
    \item \emph{Advisory} — the gate records and continues.
\end{itemize}

\end{document}

---
title: Stage reference
weight: 10
---

# Stage reference

A stage passes when its retry count stays at or below **three**. See the
[policy guide](../policy/) for the full rules.

## Fields

| Field | Type | Default |
|---|---|---|
| `name` | string | — |
| `policy` | enum | `strict` |

> Advisory gates record a failure and continue. Strict gates fail closed.

1. Validate the configuration
2. Request promotion
3. Deploy

```sh
pipeline validate --policy strict
```

<!-- Deprecated: `--legacy-gate` is removed in 2.0. -->

{
  "$schema": "https://projectious.work/schema/pipeline-2.json",
  "name": "validate-deploy",
  "policy": "strict",
  "retries": 3,
  "enabled": true,
  "owner": null,
  "budget": 12.6,
  "stages": [
    { "name": "validate", "gate": "strict", "timeoutSeconds": 120 },
    { "name": "deploy", "gate": "advisory", "timeoutSeconds": 600 }
  ],
  "tags": ["platform", "eu-central"]
}

# Pipeline definition — one policy gate per stage.
apiVersion: projectious.work/v2
kind: Pipeline
metadata:
  name: validate-deploy
  labels: { team: platform, region: eu-central }

defaults: &defaults
  policy: strict
  retries: 3
  enabled: true

spec:
  <<: *defaults
  budget: 12.60
  owner: ~
  stages:
    - name: validate
      timeoutSeconds: 120
    - name: deploy
      policy: advisory
      timeoutSeconds: 600
  owner: "platform@projectious.work"
  schema: 'https://projectious.work/schema/pipeline-2.json'
  notes: |
    Advisory gates record and continue.
    Strict gates fail closed.

# Pipeline definition — one policy gate per stage.
schema = "https://projectious.work/schema/pipeline-2.json"

[pipeline]
name    = "validate-deploy"
policy  = "strict"
retries = 3
enabled = true
budget  = 12.60
created = 2026-08-02T09:00:00Z
tags    = ["platform", "eu-central"]

[[pipeline.stage]]
name           = "validate"
gate           = "strict"
timeoutSeconds = 120

[[pipeline.stage]]
name           = "deploy"
gate           = "advisory"
timeoutSeconds = 600