@opengroundplan/core 0.1.1

package/templates/architectures/pipes-and-filters/files/docs/architecture/pipes-and-filters.node.md

@@ -0,0 +1,73 @@
+# Architecture — Pipes and Filters (TypeScript / Node)
+
+Processing is split into independent stages behind one uniform interface. A pipe connects two
+stages and carries nothing but a message; a pipe never routes and never decides.
+
+## The one rule that matters
+
+> **A stage may import `src/pipeline/contract.ts` and nothing else from the pipeline.** Not a
+> sibling stage, not `pipeline.ts`, not `config.ts`. `npm run check:stages` exits non-zero the
+> moment one does.
+
+Break it and the stages stop being reorderable, which is the only reason to pay for this
+architecture at all.
+
+## Layout
+
+```
+src/pipeline/
+  contract.ts                      # Message, Stage, StageContext, forward() — the shared contract
+  config.ts                        # every tunable and its default, read once at the composition root
+  pipeline.ts                      # THE pipeline definition: stage order + the runner
+  stages/
+    {{ firstStage | kebab }}/
+      index.ts                     # one filter; imports ../../contract.js only
+      {{ firstStage | kebab }}.test.ts  # its own test, no pipeline involved
+scripts/
+  check-stage-boundaries.mjs       # the fitness test
+```
+
+Add a stage by copying `stages/{{ firstStage | kebab }}/` and adding it to the array in
+`pipeline.ts`. Registration lives in exactly one file so reordering is a one-line diff.
+
+## Wiring it up
+
+```ts
+import { createPipelineConfig } from './pipeline/config.js';
+import { runPipeline } from './pipeline/pipeline.js';
+
+const config = createPipelineConfig(process.env);
+const result = await runPipeline(message, { config, log: console.log });
+```
+
+`PIPELINE_STAGE_TIMEOUT_MS` and `PIPELINE_MAX_ATTEMPTS` are the only knobs, and `config.ts` is
+the only place their defaults exist.
+
+## Enforcement
+
+| Guard | Command | What fails it |
+|---|---|---|
+| Stage boundary check | `npm run check:stages` | a stage importing a sibling stage, `pipeline.ts`, or `config.ts` |
+| Rule self-test | `node scripts/check-stage-boundaries.mjs --self-test` | the rule itself silently stopping to fire |
+| Per-stage tests | `npm test` | a stage that is not idempotent or drops payload keys |
+
+The checker runs its own self-test on every invocation, so a weakened rule fails before it can
+pass a broken repo. Wire `check:stages` into `lint` and into CI.
+
+## What is *not* enforced mechanically — read this part
+
+The checker is a static import check. It cannot see:
+
+- **Statelessness.** A stage holding module-level mutable state passes every check and breaks
+  the first time you run two instances. Review for it.
+- **Idempotency.** Microsoft names this non-negotiable: a stage that crashes after doing work
+  but before acknowledging *will* be re-run. Only a test can assert it — the shipped stage test
+  has an `is idempotent` case; keep one in every stage you add.
+- **Duplicate detection at the pipe.** Redelivery is a property of your queue, not of this
+  layout. Service Bus-style dedupe or an explicit seen-ids store is your job.
+- **Schema compatibility between neighbours.** `stages` is typed `readonly Stage[]`, which
+  erases the per-stage generics; reordering two stages with incompatible schemas compiles.
+  Assert it in an integration test over the real order.
+
+Sources: [Pipes and Filters pattern — Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/patterns/pipes-and-filters) ·
+[Azure-Samples/cloud-design-patterns](https://github.com/Azure-Samples/cloud-design-patterns/tree/main/pipes-and-filters).

package/templates/architectures/pipes-and-filters/files/docs/architecture/pipes-and-filters.python.md

@@ -0,0 +1,76 @@
+# Architecture — Pipes and Filters (Python)
+
+Processing is split into independent stages behind one uniform interface. A pipe connects two
+stages and carries nothing but a message; a pipe never routes and never decides.
+
+## The one rule that matters
+
+> **A stage may import `{{ solutionName | snake }}.pipeline.contract` and nothing else from the
+> pipeline.** Not a sibling stage, not `pipeline`, not `config`.
+> `tests/architecture/test_stage_boundaries.py` fails the build the moment one does.
+
+Break it and the stages stop being reorderable, which is the only reason to pay for this
+architecture at all.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/pipeline/
+  contract.py                      # Message, Stage, forward() — the shared contract
+  config.py                        # every tunable and its default, read once at the composition root
+  pipeline.py                      # THE pipeline definition: STAGES order + run_pipeline
+  stages/
+    {{ firstStage | snake }}/
+      __init__.py                  # re-exports the stage instance
+      stage.py                     # one filter; imports ...contract only
+tests/pipeline/
+  test_{{ firstStage | snake }}.py # its own test, no pipeline involved
+tests/architecture/
+  test_stage_boundaries.py         # the fitness test
+```
+
+Add a stage by copying `stages/{{ firstStage | snake }}/` and adding it to `STAGES` in
+`pipeline.py`. Registration lives in exactly one file so reordering is a one-line diff.
+
+## Wiring it up
+
+```python
+import os
+
+from {{ solutionName | snake }}.pipeline import Message, load_config, run_pipeline
+
+config = load_config(os.environ)
+result = run_pipeline(Message(id=job_id, payload={"text": raw}), config)
+```
+
+`PIPELINE_MAX_ATTEMPTS` is the only knob, and `config.py` is the only place its default exists.
+
+## Enforcement
+
+| Guard | Command | What fails it |
+|---|---|---|
+| Stage boundary fitness test | `pytest tests/architecture` | a stage importing a sibling stage, `pipeline`, or `config` |
+| Same guard, no pytest | `python tests/architecture/test_stage_boundaries.py` | the same |
+| import-linter contracts | `lint-imports` | stages coupling to each other or to the pipeline definition |
+| Per-stage tests | `pytest tests/pipeline` | a stage that is not idempotent or drops payload keys |
+
+The fitness test walks the tree, so new stages are covered with no upkeep. `.importlinter` names
+stages explicitly — add each new one to the `independence` contract.
+
+## What is *not* enforced mechanically — read this part
+
+Both guards are static import checks. They cannot see:
+
+- **Statelessness.** A stage holding module-level mutable state passes every check and breaks
+  the first time you run two workers. Review for it.
+- **Idempotency.** Microsoft names this non-negotiable: a stage that crashes after doing work
+  but before acknowledging *will* be re-run. Only a test can assert it — the shipped stage test
+  has a `test_is_idempotent` case; keep one in every stage you add.
+- **Duplicate detection at the pipe.** Redelivery is a property of your broker, not of this
+  layout. Broker-side dedupe or an explicit seen-ids store is your job.
+- **Schema compatibility between neighbours.** `STAGES` is a `Sequence[Stage]`, which says
+  nothing about payload shapes; reordering two incompatible stages type-checks. Assert it in an
+  integration test over the real order.
+
+Sources: [Pipes and Filters pattern — Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/patterns/pipes-and-filters) ·
+[import-linter](https://import-linter.readthedocs.io/).

package/templates/architectures/pipes-and-filters/files/internal/pipeline/boundary_test.go

@@ -0,0 +1,107 @@
+// Architecture fitness test for pipes and filters. One rule: from inside a stage, the only
+// importable pipeline package is the shared contract — never a sibling stage, never the
+// pipeline definition. `go test ./...` fails on a violation.
+package pipeline
+
+import (
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// Every intra-repo pipeline import contains these, whatever the module path is.
+const (
+	stagesMarker    = "/internal/pipeline/stages/"
+	pipelinePackage = "/internal/pipeline"
+	contractPackage = "/internal/pipeline/contract"
+)
+
+// stageOf returns the stage an import path points into.
+func stageOf(importPath string) string {
+	index := strings.Index(importPath, stagesMarker)
+	if index < 0 {
+		return ""
+	}
+	stage, _, _ := strings.Cut(importPath[index+len(stagesMarker):], "/")
+	return stage
+}
+
+// violation is the single rule, isolated so the self-test proves it still fires.
+func violation(fromStage, imported string) string {
+	if other := stageOf(imported); other != "" {
+		if other == fromStage {
+			return ""
+		}
+		return "imports sibling stage " + strconv.Quote(other) +
+			"; filters compose through the pipeline definition, never through each other"
+	}
+	if strings.HasSuffix(imported, contractPackage) || strings.Contains(imported, contractPackage+"/") {
+		return ""
+	}
+	if strings.HasSuffix(imported, pipelinePackage) || strings.Contains(imported, pipelinePackage+"/") {
+		return "imports " + strconv.Quote(imported) + "; a stage may import the pipeline contract and nothing else"
+	}
+	return ""
+}
+
+func TestTheRuleStillDetectsAViolation(t *testing.T) {
+	cases := []struct {
+		fromStage, imported string
+		want                bool
+	}{
+		{"resize", "x/internal/pipeline/stages/watermark", true},
+		{"resize", "x/internal/pipeline/contract", false},
+		{"resize", "x/internal/pipeline", true},
+		{"resize", "x/internal/pipeline/stages/resize/internal/util", false},
+		{"resize", "x/internal/shared/imaging", false},
+		{"resize", "strings", false},
+	}
+	for _, c := range cases {
+		if (violation(c.fromStage, c.imported) != "") != c.want {
+			t.Fatalf("violation(%q, %q): want fail=%v", c.fromStage, c.imported, c.want)
+		}
+	}
+}
+
+func TestNoStageDependsOnAnythingButTheContract(t *testing.T) {
+	const root = "stages"
+	fset := token.NewFileSet()
+
+	var failures []string
+	err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
+		if err != nil || entry.IsDir() || !strings.HasSuffix(path, ".go") {
+			return err
+		}
+
+		relative, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		stage, _, _ := strings.Cut(filepath.ToSlash(relative), "/")
+
+		file, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly)
+		if err != nil {
+			return err
+		}
+		for _, spec := range file.Imports {
+			imported, err := strconv.Unquote(spec.Path.Value)
+			if err != nil {
+				return err
+			}
+			if message := violation(stage, imported); message != "" {
+				failures = append(failures, path+": "+message)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walk %q: %v", root, err)
+	}
+	if len(failures) > 0 {
+		t.Fatalf("stage boundary violations:\n%s", strings.Join(failures, "\n"))
+	}
+}

package/templates/architectures/pipes-and-filters/files/internal/pipeline/config.go

@@ -0,0 +1,53 @@
+package pipeline
+
+import (
+	"os"
+	"strconv"
+	"time"
+)
+
+// Every pipeline tunable and its default, in one place. Stages never read the environment.
+const (
+	defaultStageTimeout = 30 * time.Second
+	defaultMaxAttempts  = 3
+)
+
+type Config struct {
+	StageTimeout time.Duration
+	MaxAttempts  int
+}
+
+// LoadConfig reads the environment once, at the composition root. Tests pass their own lookup.
+func LoadConfig(lookup func(string) (string, bool)) Config {
+	return Config{
+		StageTimeout: durationOr(lookup, "PIPELINE_STAGE_TIMEOUT", defaultStageTimeout),
+		MaxAttempts:  intOr(lookup, "PIPELINE_MAX_ATTEMPTS", defaultMaxAttempts),
+	}
+}
+
+// DefaultConfig is the production wiring.
+func DefaultConfig() Config { return LoadConfig(os.LookupEnv) }
+
+func durationOr(lookup func(string) (string, bool), key string, fallback time.Duration) time.Duration {
+	raw, ok := lookup(key)
+	if !ok {
+		return fallback
+	}
+	value, err := time.ParseDuration(raw)
+	if err != nil || value <= 0 {
+		return fallback
+	}
+	return value
+}
+
+func intOr(lookup func(string) (string, bool), key string, fallback int) int {
+	raw, ok := lookup(key)
+	if !ok {
+		return fallback
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil || value <= 0 {
+		return fallback
+	}
+	return value
+}

package/templates/architectures/pipes-and-filters/files/internal/pipeline/contract/contract.go

@@ -0,0 +1,35 @@
+// Package contract is the shared stage contract — the only package a stage may import from the
+// pipeline. Stages know their input and output schema and nothing about each other.
+package contract
+
+import "context"
+
+// Message is the envelope carried on a pipe.
+type Message struct {
+	// ID is stable for the life of one unit of work — it is the key a stage dedupes on.
+	ID string
+
+	// Attempt is incremented by whatever redelivers the message; the runner refuses past MaxAttempts.
+	Attempt int
+
+	Payload map[string]any
+	Meta    map[string]any
+}
+
+// Stage is the uniform interface. Reordering stages is only safe while this is all they share.
+type Stage interface {
+	Name() string
+	Run(ctx context.Context, in Message) (Message, error)
+}
+
+// Forward carries ID, Attempt and unread Meta on, so a stage never drops data it does not own.
+func Forward(in Message, payload map[string]any, meta map[string]any) Message {
+	merged := make(map[string]any, len(in.Meta)+len(meta))
+	for key, value := range in.Meta {
+		merged[key] = value
+	}
+	for key, value := range meta {
+		merged[key] = value
+	}
+	return Message{ID: in.ID, Attempt: in.Attempt, Payload: payload, Meta: merged}
+}

package/templates/architectures/pipes-and-filters/files/internal/pipeline/pipeline.go

@@ -0,0 +1,39 @@
+// Package pipeline holds the pipeline definition: the order of the stages and the runner that
+// drives them. Stages live below it and must never import it back.
+package pipeline
+
+import (
+	"context"
+	"fmt"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/pipeline/contract"
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/pipeline/stages/{{ firstStage | lower }}"
+)
+
+// Stages is the pipeline definition. The order lives here and nowhere else, which is what keeps
+// filters reorderable.
+func Stages() []contract.Stage {
+	return []contract.Stage{
+		{{ firstStage | lower }}.New(),
+	}
+}
+
+// Run drives one message through every stage. Each stage gets its own deadline because a pipe
+// is a failure boundary, not just a connector. Retry and backoff belong around this call.
+func Run(ctx context.Context, cfg Config, in contract.Message) (contract.Message, error) {
+	if in.Attempt > cfg.MaxAttempts {
+		return in, fmt.Errorf("message %s exceeded %d attempts", in.ID, cfg.MaxAttempts)
+	}
+
+	current := in
+	for _, stage := range Stages() {
+		stageCtx, cancel := context.WithTimeout(ctx, cfg.StageTimeout)
+		out, err := stage.Run(stageCtx, current)
+		cancel()
+		if err != nil {
+			return current, fmt.Errorf("stage %s: %w", stage.Name(), err)
+		}
+		current = out
+	}
+	return current, nil
+}

package/templates/architectures/pipes-and-filters/files/internal/pipeline/stages/__firstStage.lower__/__firstStage.lower__.go

@@ -0,0 +1,42 @@
+// Package {{ firstStage | lower }} is one filter: a single job, no state, safe to run twice.
+// Copy this package to add a stage — contract is the only pipeline package it may import.
+package {{ firstStage | lower }}
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strings"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/pipeline/contract"
+)
+
+var whitespace = regexp.MustCompile(`\s+`)
+
+type Stage struct{}
+
+func New() Stage { return Stage{} }
+
+func (Stage) Name() string { return "{{ firstStage | kebab }}" }
+
+// Run collapses runs of whitespace. Idempotent by construction: on a pipe, duplicate delivery
+// is a guarantee, not an edge case.
+func (s Stage) Run(ctx context.Context, in contract.Message) (contract.Message, error) {
+	if err := ctx.Err(); err != nil {
+		return in, err
+	}
+
+	text, ok := in.Payload["text"].(string)
+	if !ok {
+		return in, fmt.Errorf("%s: payload has no string field %q", s.Name(), "text")
+	}
+
+	// Unknown keys are copied through untouched — a filter tolerates data it does not own.
+	payload := make(map[string]any, len(in.Payload))
+	for key, value := range in.Payload {
+		payload[key] = value
+	}
+	payload["text"] = strings.TrimSpace(whitespace.ReplaceAllString(text, " "))
+
+	return contract.Forward(in, payload, nil), nil
+}

package/templates/architectures/pipes-and-filters/files/internal/pipeline/stages/__firstStage.lower__/__firstStage.lower___test.go

@@ -0,0 +1,59 @@
+package {{ firstStage | lower }}
+
+import (
+	"context"
+	"testing"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/pipeline/contract"
+)
+
+// A stage test needs no pipeline and no sibling — that is the point of the uniform interface.
+func message(text string) contract.Message {
+	return contract.Message{ID: "test-1", Attempt: 1, Payload: map[string]any{"text": text}}
+}
+
+func TestCollapsesRunsOfWhitespace(t *testing.T) {
+	out, err := New().Run(context.Background(), message("  a   b "))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := out.Payload["text"]; got != "a b" {
+		t.Fatalf("got %q, want %q", got, "a b")
+	}
+}
+
+// Duplicate delivery is guaranteed on a pipe, so a second run must change nothing.
+func TestIsIdempotent(t *testing.T) {
+	once, err := New().Run(context.Background(), message(" a  b "))
+	if err != nil {
+		t.Fatal(err)
+	}
+	twice, err := New().Run(context.Background(), once)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if twice.Payload["text"] != once.Payload["text"] {
+		t.Fatalf("second run changed the payload: %v", twice.Payload)
+	}
+}
+
+func TestPreservesMessageIDSoDownstreamStagesCanDedupe(t *testing.T) {
+	out, err := New().Run(context.Background(), message("x"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.ID != "test-1" {
+		t.Fatalf("got %q, want %q", out.ID, "test-1")
+	}
+}
+
+func TestPassesThroughPayloadKeysItDoesNotOwn(t *testing.T) {
+	in := contract.Message{ID: "test-1", Attempt: 1, Payload: map[string]any{"text": " a ", "width": 800}}
+	out, err := New().Run(context.Background(), in)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Payload["width"] != 800 {
+		t.Fatalf("dropped a key it does not own: %v", out.Payload)
+	}
+}

package/templates/architectures/pipes-and-filters/files/package.json

@@ -0,0 +1,8 @@
+{
+  "scripts": {
+    "check:stages": "node scripts/check-stage-boundaries.mjs"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
+}

package/templates/architectures/pipes-and-filters/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/pipes-and-filters/files/scripts/check-stage-boundaries.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Architecture fitness test for pipes and filters.
+ *
+ * One rule: from inside a stage, the only importable pipeline module is the shared contract.
+ * Not a sibling stage, not the pipeline definition, not the pipeline config. Exits non-zero on
+ * a violation, so it belongs in `lint` and in CI, not in a README.
+ *
+ * It reads import specifiers as written and never resolves them on disk, so it is immune to
+ * TypeScript/bundler resolution differences and works the same on .ts and .js.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Every tunable lives here. Nothing below reads the environment directly. */
+const config = {
+  pipelineRoot: process.env.ARCH_PIPELINE_ROOT ?? 'src/pipeline',
+  stagesDir: process.env.ARCH_STAGES_DIR ?? 'stages',
+  /** The one module a stage may import, relative to pipelineRoot. */
+  contractModule: process.env.ARCH_CONTRACT_MODULE ?? 'contract',
+  extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'],
+  skipDirs: ['node_modules', 'dist', 'build', 'out', 'coverage', '.git', '.turbo', '.next'],
+};
+
+const stagesRoot = () => path.posix.join(config.pipelineRoot, config.stagesDir);
+const contractPath = () => path.posix.join(config.pipelineRoot, config.contractModule);
+
+const SPECIFIER_PATTERNS = [
+  /(?:^|[\s;}])(?:import|export)[^;]*?\sfrom\s*['"]([^'"]+)['"]/g,
+  /(?:^|[\s;}])import\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+
+export function specifiersOf(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return [...found];
+}
+
+/** The stage a repo path belongs to, or null when it is outside every stage. */
+export function stageOf(filePath) {
+  const root = stagesRoot() + '/';
+  if (!filePath.startsWith(root)) return null;
+  return filePath.slice(root.length).split('/')[0] || null;
+}
+
+function withoutExtension(filePath) {
+  const extension = path.posix.extname(filePath);
+  return config.extensions.includes(extension) ? filePath.slice(0, -extension.length) : filePath;
+}
+
+function isContract(target) {
+  const bare = withoutExtension(target);
+  return bare === contractPath() || bare.startsWith(contractPath() + '/');
+}
+
+/** The single rule, isolated so `--self-test` can prove it still fires. */
+export function violationOf(fromFile, specifier) {
+  const from = stageOf(fromFile);
+  if (!from) return null; // only code inside a stage is constrained
+
+  if (!specifier.startsWith('.')) {
+    // A package path through `stages/` is a sibling import wearing a workspace alias.
+    return specifier.split('/').includes(config.stagesDir)
+      ? `imports "${specifier}" — that is a sibling stage behind a package name`
+      : null;
+  }
+
+  const target = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+  const to = stageOf(target);
+  if (to) {
+    return to === from
+      ? null
+      : `imports "${specifier}" — stage "${to}" is a sibling filter; stages compose through ` +
+          `${config.pipelineRoot}/pipeline, never through each other`;
+  }
+
+  if (isContract(target)) return null;
+
+  const insidePipeline =
+    target === config.pipelineRoot || target.startsWith(config.pipelineRoot + '/');
+  return insidePipeline
+    ? `imports "${specifier}" — a stage may import ${contractPath()} and nothing else from the pipeline`
+    : null;
+}
+
+async function listFiles(root) {
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.posix.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!config.skipDirs.includes(entry.name)) await walk(child);
+      } else if (config.extensions.includes(path.posix.extname(entry.name))) {
+        found.push(child);
+      }
+    }
+  };
+  await walk(root);
+  return found;
+}
+
+async function discoverStages() {
+  const entries = await readdir(stagesRoot(), { withFileTypes: true }).catch(() => []);
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+
+const SELF_TEST_CASES = [
+  ['src/pipeline/stages/resize/index.ts', '../watermark/index.js', true],
+  ['src/pipeline/stages/resize/index.ts', '../../contract.js', false],
+  ['src/pipeline/stages/resize/index.ts', '../../pipeline.js', true],
+  ['src/pipeline/stages/resize/index.ts', '../../config.js', true],
+  ['src/pipeline/stages/resize/index.ts', './helpers.js', false],
+  ['src/pipeline/stages/resize/index.ts', '@app/stages/watermark', true],
+  ['src/pipeline/stages/resize/index.ts', 'node:crypto', false],
+  ['src/pipeline/pipeline.ts', './stages/resize/index.js', false],
+];
+
+function selfTest() {
+  const wrong = SELF_TEST_CASES.filter(
+    ([file, specifier, expected]) => Boolean(violationOf(file, specifier)) !== expected,
+  );
+  for (const [file, specifier] of wrong) console.error(`self-test failed: ${file} -> ${specifier}`);
+  return wrong.length === 0;
+}
+
+async function main() {
+  if (process.argv.includes('--self-test')) {
+    console.log(`stage boundary rule verified against ${SELF_TEST_CASES.length} cases`);
+    return;
+  }
+
+  const stages = await discoverStages();
+  if (stages.length === 0) {
+    // A silent pass over an empty file set is the failure mode this check exists to avoid.
+    console.error(`No stages found under ${stagesRoot()} — is ARCH_PIPELINE_ROOT right?`);
+    process.exit(1);
+  }
+
+  const files = await listFiles(stagesRoot());
+  const violations = [];
+  for (const file of files) {
+    const source = await readFile(file, 'utf8');
+    for (const specifier of specifiersOf(source)) {
+      const violation = violationOf(file, specifier);
+      if (violation) violations.push(`${file}: ${violation}`);
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error(`Stage boundary violations (${violations.length}):\n` + violations.join('\n'));
+    process.exit(1);
+  }
+  console.log(`Stage boundaries hold across ${stages.length} stage(s), ${files.length} file(s).`);
+}
+
+if (!selfTest()) {
+  console.error('The boundary rule no longer detects a known violation — fix violationOf().');
+  process.exit(1);
+}
+await main();