graceful-boundaries 1.5.0

package/CONFORMANCE.md

@@ -0,0 +1,78 @@
+# Conformance
+
+Graceful Boundaries defines five conformance levels plus a "no agentic surface" baseline. Each level is independently testable via the eval suite at `evals/`.
+
+## Levels
+
+| Level | Key requirement |
+|---|---|
+| N/A | No agentic interaction surface — the service does not expose an HTTP API or agentic surface that callers consume programmatically |
+| 0 | Limits exist but are not described per the spec — operational behavior only, no normative response bodies |
+| 1 | All non-success responses include `error`, `detail`, `why`. 429 responses also include `limit` and `retryAfterSeconds`. |
+| 2 | Level 1 + a discoverable limits endpoint at `/.well-known/limits` (or the path advertised in `Link: rel="limits"`) returning a structured limits document |
+| 3 | Level 2 + constructive guidance fields where applicable: `cachedResultUrl`, `alternativeEndpoint`, `upgradeUrl`. Guidance MUST be honest (point at working alternatives, not dead ends). |
+| 4 | Level 3 + proactive `RateLimit` headers on success responses, per RFC 9239-equivalent semantics, so callers can adapt before hitting refusal |
+
+A higher level subsumes all lower levels. A Level 3 service is also Level 2, 1, and not N/A.
+
+## Verifier
+
+The reference verifier is `evals/check.js`. Run against any HTTPS service:
+
+```bash
+node evals/check.js https://example.com
+node evals/check.js https://example.com --json
+node evals/check.js https://example.com --limits-path /custom-limits
+```
+
+A passing run reports the highest level the service satisfies. The verifier is the conformance target — any implementation passing the eval suite is conformant.
+
+## Test suite
+
+`evals/` ships 250 tests across 12 files:
+
+| File | Coverage |
+|---|---|
+| `test-conformance.js` | End-to-end level checks |
+| `test-response-classes.js` | Response class structure |
+| `test-refusal.js` | Refusal body shape (`error`, `detail`, `why`, `limit`, `retryAfterSeconds`) |
+| `test-discovery.js` | Limits discovery endpoint |
+| `test-action-boundaries.js` | Action boundary fields |
+| `test-agentic-surfaces.js` | Agent-facing surface inventory |
+| `test-proactive-headers.js` | Level 4 proactive headers |
+| `test-html-refusal.js` | HTML refusal binding |
+| `test-security.js` | Security-case responses (SC-1 through SC-16) |
+| `test-schemas.js` | Published JSON Schemas vs spec examples, worked limits examples, and checker agreement |
+| `test-middleware-examples.js` | Drop-in middleware examples emit conformant bodies |
+| `test-agent-behavior.js` | Agent-side compliance fixtures (retry, guidance, SC-6, SC-16) |
+
+Run all: `npm test`. No npm dependencies — vanilla Node.js.
+
+## Reference implementation
+
+Siteline (https://siteline.to/) is the canonical Level 4 reference implementation.
+
+```bash
+node evals/check.js https://siteline.to
+```
+
+When proposing a normative change that would alter Siteline's level, coordinate the release with Siteline so the reference stays current.
+
+## Independent verifiers
+
+Anyone may build a conformant verifier. The eval suite is the agreement target. The hosted verifier at https://gracefulboundaries.dev/ is published for convenience and MUST NOT be treated as the only authoritative implementation.
+
+## What conformance does not assert
+
+- **Safety.** Conformance verifies form. It does not assert that the service is benign, well-operated, or appropriate for any use case.
+- **Fairness.** Conformance does not evaluate whether the limit values are reasonable, only whether they are communicated correctly.
+- **Availability.** Conformance does not measure uptime, latency, or operational quality.
+- **Authorization correctness.** Conformance does not validate that the service's authorization decisions are correct, only that refusals are well-formed.
+
+## Reporting findings
+
+When `evals/check.js` reports a level lower than claimed, file a finding in the service operator's issue tracker with the failing test output. The eval suite produces machine-readable JSON via `--json` for inclusion in tickets.
+
+## Versioning
+
+Conformance is versioned with the spec. A service claiming "Level 3 conformance" SHOULD specify the spec version (e.g. "Level 3 against Graceful Boundaries 1.4.1"). Major spec version increments require re-evaluation; minor and patch versions are backward-compatible.

package/LICENSE

@@ -0,0 +1,36 @@
+MIT License
+
+Copyright (c) 2026 PAICE.work PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+License scope
+
+- LICENSE (this file, MIT): applies to all code in the repository — eval suite,
+  conformance checker (evals/), reference implementations, scripts, and any
+  example code embedded in documentation.
+- LICENSE-SPEC (CC BY 4.0): applies to spec.md, docs/*.md, and the textual
+  content of the specification itself.
+
+Files containing both code and prose follow the prose license for the prose
+portions and the MIT license for the code portions. The split is non-binding
+when a single file mixes both; treat the file as MIT for code reuse and
+CC BY 4.0 for textual quotation.

package/LICENSE-SPEC

@@ -0,0 +1,12 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+Copyright (c) 2026 PAICE.work PBC
+
+You are free to:
+- Share: copy and redistribute the material in any medium or format
+- Adapt: remix, transform, and build upon the material for any purpose, even commercially
+
+Under the following terms:
+- Attribution: You must give appropriate credit, provide a link to the license, and indicate if changes were made.
+
+Full license text: https://creativecommons.org/licenses/by/4.0/legalcode

package/README.md

@@ -0,0 +1,262 @@
+# Graceful Boundaries
+
+A specification for how services communicate their operational limits to humans and autonomous agents.
+
+**[gracefulboundaries.dev](https://gracefulboundaries.dev)**
+
+[![License: CC-BY-4.0](https://img.shields.io/badge/License-CC--BY--4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
+[![Version](https://img.shields.io/badge/version-1.5.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/github/actions/workflow/status/snapsynapse/graceful-boundaries/test.yml?label=tests)](https://github.com/snapsynapse/graceful-boundaries/actions)
+[![ClawHub](https://img.shields.io/badge/ClawHub-83%20installs-blue)](https://clawhub.ai/snapsynapse/graceful-boundaries)
+
+## Who this is for
+
+API and service operators, plus the agent builders calling them, who need operational limits expressed in a way autonomous callers can actually act on.
+
+## What problem it solves
+
+Services signal limits with status codes (429, 403, 500) that agents can't interpret, so agents retry blindly and the waste compounds. Graceful Boundaries is a specification for communicating operational limits to humans and autonomous agents.
+
+## Canonical URL
+
+https://gracefulboundaries.dev/
+
+## The problem
+
+Every unclear response generates follow-up traffic. A vague `429` causes blind retries. A vague `403` causes re-attempts with different credentials. A generic `500` causes indefinite retries. When autonomous agents are the caller, the waste compounds: agents retry faster, probe more systematically, and lack the human judgment to know when to stop.
+
+Most services enforce rate limits but communicate them poorly. A `429 Too Many Requests` with `Retry-After: 60` tells a retry loop what to do. It doesn't tell an autonomous agent whether to retry, use a cached result, try a different endpoint, or inform the human. It doesn't tell a developer what the limits are before they hit them. It doesn't tell anyone *why* the limit exists.
+
+## What Graceful Boundaries does
+
+The specification addresses three gaps that existing standards cover separately but no specification combines:
+
+1. **Proactive discovery** -- limits are machine-readable before they are hit
+2. **Structured refusal** -- every non-success response explains what happened, why, and what to do next
+3. **Constructive guidance** -- refusals include a useful next step, not just a block
+
+This applies to **every HTTP error class**, not just rate limits. A `400` explains the validation rule and its security rationale. A `404` tells you whether the resource never existed or expired, and offers a creation path. A `500` names the affected subsystem and suggests a retry window. Every non-success response MUST include `error`, `detail`, and `why`.
+
+**Read the full specification:** **[spec.md](spec.md)**
+
+## See it in action
+
+These examples use [Siteline](https://siteline.to/), a Level 4 conformant reference implementation.
+
+**Discover limits before hitting them:**
+
+```bash
+curl -s https://siteline.to/api/limits | jq '{service, limits: .limits.scan}'
+```
+
+```json
+{
+  "service": "Siteline",
+  "limits": {
+    "scan": {
+      "endpoint": "/api/scan",
+      "method": "GET",
+      "limits": [
+        {
+          "type": "ip-rate",
+          "maxRequests": 10,
+          "windowSeconds": 3600,
+          "description": "10 scans per IP per hour."
+        }
+      ]
+    }
+  }
+}
+```
+
+**Structured refusal with constructive guidance** (when a rate limit is exceeded):
+
+```json
+{
+  "error": "rate_limit_exceeded",
+  "detail": "You can run up to 10 scans per hour. Try again in 2400 seconds.",
+  "limit": "10 scans per IP per hour",
+  "retryAfterSeconds": 2400,
+  "why": "Siteline is a free service. Rate limits keep it available for everyone and prevent abuse.",
+  "alternativeEndpoint": "/api/result?id=example.com"
+}
+```
+
+The caller knows the limit, when to retry, *why* the limit exists, and where to get the result without waiting.
+
+**Every error class is self-explanatory**, not just 429s:
+
+```json
+{
+  "error": "invalid_input",
+  "detail": "This URL is outside the scanner's accepted public-target policy.",
+  "why": "Siteline accepts only public scan targets to prevent the scanner from being used as a proxy.",
+  "field": "url",
+  "expected": "A public URL with a resolvable hostname."
+}
+```
+
+An agent reading this `400` understands the input-safety policy and can fix the input. Without `why`, it would blindly retry with different URLs.
+
+**Proactive headers on successful responses:**
+
+```bash
+curl -s 'https://siteline.to/api/result?id=example.com' \
+  -D - -o /dev/null 2>&1 | grep ratelimit
+```
+
+```
+ratelimit: limit=60, remaining=59, reset=60
+ratelimit-policy: 60;w=60
+```
+
+A caller seeing `remaining=1` self-throttles before the next request. A caller seeing `remaining=59` knows it has budget.
+
+For more examples, see **[docs/curl-examples.md](docs/curl-examples.md)**.
+
+## Conformance levels
+
+Services self-declare a conformance level. The eval suite validates the claim.
+
+| Level | What it requires |
+|---|---|
+| **N/A: Not Applicable** | No API endpoints, rate limits, or agentic interaction surface. |
+| **Level 0: Non-Conformant** | Limits exist but are not described per this specification. |
+| **Level 1: Structured Refusal** | All non-success responses include `error`, `detail`, and `why`. All `429`s add `limit` and `retryAfterSeconds`. |
+| **Level 2: Discoverable** | Level 1 + a limits discovery endpoint. |
+| **Level 3: Constructive** | Level 2 + refusal responses include constructive guidance when applicable. |
+| **Level 4: Proactive** | Level 3 + successful responses include proactive limit headers. |
+
+## Evaluate conformance
+
+Run the checker directly via npx (no install, no dependencies):
+
+```bash
+npx graceful-boundaries check https://siteline.to     # Level 4 — proactive headers
+npx graceful-boundaries check https://google.com      # Level 0 — no conformance
+npx graceful-boundaries check https://your-service.com --json
+npx graceful-boundaries check https://your-service.com --min-level 2   # nonzero exit below Level 2
+npx graceful-boundaries check https://your-service.com --check-cloaking
+```
+
+![Checker output: Siteline confirms Level 4, Google confirms Level 0](imgs/checker-demo.svg)
+
+Or clone and run from the project root with `node evals/check.js <url>`. Run the unit test suite (250 tests, no dependencies):
+
+```bash
+npm test
+```
+
+### Gate conformance in CI
+
+The repo doubles as a composite GitHub Action. Add a job that fails when your deployed service drops below its declared level:
+
+```yaml
+- uses: snapsynapse/graceful-boundaries@v1
+  with:
+    url: https://staging.your-service.com
+    min-level: "2"
+```
+
+Levels 2 and 4 are confirmable passively and make reliable CI gates; Levels 1 and 3 require observing a live refusal (see [CONFORMANCE.md](CONFORMANCE.md)).
+
+## Assistant guide
+
+Graceful Boundaries adopts the [GuideCheck](https://guidecheck.org/) Human-Verifiable Assistant Guide profile. The assistant-facing guide is committed at [assistant-guide.txt](assistant-guide.txt) and published from `https://gracefulboundaries.dev/.well-known/assistant-guide.txt`.
+
+Verify the guide before asking an assistant to follow it. Use the hosted verifier at [guidecheck.org/verify](https://guidecheck.org/verify) or a conformant local verifier:
+
+```bash
+python3 /path/to/guidecheck/scripts/guidecheck_verify.py assistant-guide.txt
+```
+
+The committed root copy and the well-known copy must remain byte-identical.
+
+The current GuideCheck implementation and all agent-facing repository surfaces are documented in [docs/agentic-surfaces.md](docs/agentic-surfaces.md). Current local verification: GuideCheck reference verifier 0.3.2, achieved Level 3, guide SHA-256 `7dbf6472d5a49905054b0d541c27a4246bdc1f10e5d7bb9c16c028fa04b8bfdd`, with 0 blocking findings and 0 warnings.
+
+## Which level should you target?
+
+- **No API or agentic surface?** Declare `not-applicable` — takes 5 minutes.
+- **API with rate limits?** Start at **Level 1** (structured refusals). This is the minimum useful level.
+- **Agents call your API?** Target **Level 2** (add discovery) so agents learn the rules before breaking them.
+- **Want to reduce 429 traffic?** Target **Level 3** (constructive guidance) — offer cached results and alternatives instead of bare refusals.
+- **High-traffic API with agent callers?** Target **Level 4** (proactive headers) — callers self-throttle before hitting limits.
+
+For a step-by-step walkthrough with code samples, see the **[implementation guide](docs/implementation-guide.md)**.
+
+## Adopt in an afternoon
+
+The shortest path from "read the spec" to "conformant service":
+
+1. **Copy a middleware example** -- dependency-free Level 2 implementations (Level 4 with one flag) for [Express, FastAPI, Cloudflare Workers, and Hono](examples/middleware/).
+2. **Copy the nearest limits.json** -- complete discovery responses for a [SaaS API, free scanner, LLM API, and content site](examples/limits/).
+3. **Validate your bodies** -- published [JSON Schemas](schema/) for refusals, 429s, and the discovery endpoint, served at `https://gracefulboundaries.dev/schema/`. Importable into OpenAPI and CI validators.
+4. **Verify** -- `npx graceful-boundaries check https://your-service.example`, then gate it in CI with the GitHub Action above.
+5. **Declare** -- add yourself to [ADOPTERS.md](ADOPTERS.md) and embed a [conformance badge](ADOPTERS.md#badges).
+
+Already emitting RFC 9457 Problem Details? You can adopt without changing your content type: see the [RFC 9457 compatibility profile](docs/rfc9457-profile.md).
+
+Building the agent side? `evals/test-agent-behavior.js` is an [agent compliance suite](evals/test-agent-behavior.js): point it at your retry/refusal-handling logic and it checks you respect `retryAfterSeconds`, prefer cached results, ignore off-origin guidance URLs (SC-6), and treat guidance text as untrusted data (SC-16).
+
+## Adopt the spec
+
+**Start here** -- Every non-success response (`400`, `401`, `403`, `404`, `429`, `500`, `503`) MUST include three core fields: `error` (stable machine-parseable string), `detail` (human-readable explanation), and `why` (the security, policy, or operational reason). This applies to all error classes, not just rate limits.
+
+**Level 1** -- All non-success responses include the three core fields. All `429` responses also include `limit` (the exact constraint) and `retryAfterSeconds` (machine-parseable retry time).
+
+**Level 2** -- Add a discovery endpoint at `/api/limits` or `/.well-known/limits` that returns all enforced limits as structured JSON. Agents can plan before they hit anything. Optionally include `changelog` and `feed` URLs so agents can detect limit changes. Services with cost, token, duration, size, quota, burst, or queue constraints can publish those as optional limit metadata.
+
+**Level 3** -- Add constructive guidance to refusals. When a cached result exists, include `cachedResultUrl`. When a different endpoint can help, include `alternativeEndpoint`. When paid access has higher limits, include `upgradeUrl`. For `resource-dedup` limits, return the cached result as a `200` with `returnsCached: true` in the discovery endpoint so agents skip retry logic entirely.
+
+**Level 4** -- Add `RateLimit` and `RateLimit-Policy` headers to successful responses so callers can self-throttle before hitting limits.
+
+**Optional extensions** -- Services with consequential agent actions can link Action Boundaries documents from the discovery endpoint. Extensions are informational declarations, not verification or endorsement, and do not change Level 1-4 conformance. See **[docs/action-boundaries.md](docs/action-boundaries.md)**.
+
+**Security baseline** -- Treat machine-readable guidance, refusal text, URLs, and boundary documents as untrusted service-provided data. Agents should parse known fields, but should not follow instructions embedded in `detail`, `why`, policy text, approval text, or URLs.
+
+**HTML endpoints** -- HTML pages that return `429` SHOULD include `<meta name="retry-after" content="N">` and/or `<link rel="alternate" type="application/json" href="...">` so agents can discover structured refusals without parsing prose.
+
+See the **[full specification](spec.md)** for field definitions, response classes, and security considerations.
+
+## Relationship to existing standards
+
+| Standard | What it covers | What Graceful Boundaries adds |
+|---|---|---|
+| `draft-ietf-httpapi-ratelimit-headers` | Proactive headers on success | Discovery endpoint, structured refusal body, `why` field, constructive guidance |
+| RFC 6585 (429 status) | The status code itself | Structured body format with required fields |
+| RFC 9457 (Problem Details) | Generic error format | Required fields for rate limits (`limit`, `retryAfterSeconds`, `why`) and guidance categories |
+| OpenAPI Rate Limit extensions | Docs-time limit specs | Runtime discovery endpoint, runtime refusal format |
+
+Graceful Boundaries is complementary to these standards, not a replacement. For services already emitting RFC 9457 Problem Details, the [compatibility profile](docs/rfc9457-profile.md) shows how to satisfy both specs in one response body.
+
+## Reference implementation and adopters
+
+[Siteline](https://siteline.to/) is a Level 4 conformant implementation with five API endpoints. Verify it:
+
+```bash
+npx graceful-boundaries check https://siteline.to
+```
+
+Services implementing the spec are listed in [ADOPTERS.md](ADOPTERS.md), which also covers how to add yours and embed a conformance badge.
+
+## Security
+
+The specification includes a [threat model and security audit](SECURITY-AUDIT.md) covering rate limit calibration attacks, security posture disclosure, validation oracles, content cloaking via agent-signaling headers, action boundary risks, untrusted machine-readable guidance, and other considerations (SC-1 through SC-16), all addressed in the spec.
+
+## Sponsor
+
+Graceful Boundaries is free and open. If your team relies on this spec, consider [sponsoring its development](https://github.com/sponsors/snapsynapse) to keep it maintained and evolving. See [SPONSORS.md](SPONSORS.md).
+
+## License
+
+CC-BY-4.0. Use it, adapt it, build on it. Attribution required.
+
+## About
+
+Graceful Boundaries is a [PAICE.work](https://paice.work/) project. PAICE.work PBC is a public benefit corporation dedicated to enabling safer and more effective People+AI collaboration. We believe that clear, honest communication between services and their callers (human or AI agent) is foundational to trustworthy AI infrastructure. This specification is part of that mission.
+
+The patterns in this spec emerged from building [Siteline](https://siteline.to/), an AI agent readiness scanner, where the quality of the refusal matters as much as the enforcement.
+
+The conformance audit skill is available on **[ClawHub](https://clawhub.ai/snapsynapse/graceful-boundaries)**.
+
+See also: **[GuideCheck](https://guidecheck.org/)** -- human-verifiable assistant guides, and **[Skill Provenance](https://skillprovenance.dev/)** -- version identity that travels with agent skill bundles. Also PAICE.work projects.

package/bin/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * npx entry point for the Graceful Boundaries conformance checker.
+ *
+ * Usage:
+ *   npx graceful-boundaries check <base-url> [--limits-path /path] [--json] [--check-cloaking] [--min-level N]
+ *   npx graceful-boundaries <base-url>          # "check" subcommand is optional
+ *
+ * Thin wrapper around evals/check.js. All flags pass through unchanged.
+ */
+
+const { main } = require("../evals/check.js");
+
+// Strip the optional "check" subcommand so check.js sees the URL as the first arg.
+if (process.argv[2] === "check") {
+  process.argv.splice(2, 1);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});