graceful-boundaries 1.5.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "graceful-boundaries",
+  "version": "1.5.0",
+  "description": "A specification for how services communicate their operational limits to humans and autonomous agents.",
+  "license": "CC-BY-4.0 AND MIT",
+  "bin": {
+    "graceful-boundaries": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "evals/check.js",
+    "schema/",
+    "spec.md",
+    "CONFORMANCE.md",
+    "LICENSE",
+    "LICENSE-SPEC"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node evals/test-refusal.js && node evals/test-response-classes.js && node evals/test-security.js && node evals/test-conformance.js && node evals/test-discovery.js && node evals/test-action-boundaries.js && node evals/test-proactive-headers.js && node evals/test-html-refusal.js && node evals/test-agentic-surfaces.js && node evals/test-schemas.js && node evals/test-middleware-examples.js && node evals/test-agent-behavior.js",
+    "test:agent": "node evals/test-agent-behavior.js",
+    "test:schemas": "node evals/test-schemas.js",
+    "test:middleware": "node evals/test-middleware-examples.js",
+    "test:html": "node evals/test-html-refusal.js",
+    "test:refusal": "node evals/test-refusal.js",
+    "test:classes": "node evals/test-response-classes.js",
+    "test:security": "node evals/test-security.js",
+    "test:conformance": "node evals/test-conformance.js",
+    "test:discovery": "node evals/test-discovery.js",
+    "test:actions": "node evals/test-action-boundaries.js",
+    "test:headers": "node evals/test-proactive-headers.js",
+    "test:agentic": "node evals/test-agentic-surfaces.js",
+    "check": "node evals/check.js"
+  },
+  "type": "commonjs",
+  "author": "PAICE.work PBC <https://paice.work/>",
+  "homepage": "https://gracefulboundaries.dev",
+  "bugs": {
+    "url": "https://github.com/snapsynapse/graceful-boundaries/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snapsynapse/graceful-boundaries"
+  },
+  "keywords": [
+    "graceful-boundaries",
+    "rate-limiting",
+    "api",
+    "specification",
+    "conformance",
+    "autonomous-agents",
+    "429",
+    "structured-refusal",
+    "limits-discovery"
+  ]
+}

package/schema/limits.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gracefulboundaries.dev/schema/limits.schema.json",
+  "title": "Graceful Boundaries limits discovery response",
+  "description": "Response shape for the limits discovery endpoint (GET /api/limits or GET /.well-known/limits) per Graceful Boundaries. Spec: https://gracefulboundaries.dev/spec",
+  "type": "object",
+  "required": ["service", "description", "limits"],
+  "properties": {
+    "service": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Service name."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What the service does."
+    },
+    "conformance": {
+      "type": "string",
+      "enum": ["not-applicable", "none", "level-1", "level-2", "level-3", "level-4"],
+      "description": "Self-declared conformance level. A self-assertion; external agents validate it against actual behavior."
+    },
+    "changelog": {
+      "type": "string",
+      "description": "URL to a changelog resource for limit changes. Must be a relative path or same-origin absolute URL."
+    },
+    "feed": {
+      "type": "string",
+      "description": "URL to a feed (JSON Feed, Atom, RSS) for change notifications. Must be a relative path or same-origin absolute URL."
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Named extension discovery URLs (e.g. actionBoundaries). Each value must be a relative path or same-origin absolute URL. Presence does not affect Level 1-4 conformance."
+    },
+    "limits": {
+      "type": "object",
+      "description": "Map of endpoint keys to documented endpoint limits. May be empty for not-applicable or none declarations.",
+      "additionalProperties": { "$ref": "#/$defs/endpointEntry" }
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "endpointEntry": {
+      "type": "object",
+      "required": ["endpoint", "method", "limits"],
+      "properties": {
+        "endpoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path pattern, e.g. /api/scan."
+        },
+        "method": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HTTP method."
+        },
+        "limits": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/limitEntry" }
+        },
+        "note": {
+          "type": "string",
+          "description": "Additional context for this endpoint."
+        },
+        "agentCapable": {
+          "type": "boolean",
+          "description": "Reserved (roadmap): whether the endpoint is designed for machine consumption."
+        }
+      },
+      "additionalProperties": true
+    },
+    "limitEntry": {
+      "type": "object",
+      "required": ["type", "maxRequests", "windowSeconds", "description"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Limit category: ip-rate, key-rate, user-rate, global-rate, resource-dedup, cooldown, concurrency, quota, cost-limit, burst-rate, or a service-defined type."
+        },
+        "limitId": {
+          "type": "string",
+          "description": "Stable identifier for this specific limit."
+        },
+        "limitType": {
+          "type": "string",
+          "description": "Explicit copy of the limit type when multiple limits interact."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Subject of the limit: ip, key, user, resource, or global."
+        },
+        "maxRequests": {
+          "type": "number",
+          "description": "Maximum requests in the window."
+        },
+        "windowSeconds": {
+          "type": "number",
+          "description": "Window duration in seconds."
+        },
+        "costMetric": {
+          "type": "string",
+          "description": "Resource unit for quota or cost limits: tokens, credits, bytes, dollars."
+        },
+        "maxInputBytes": { "type": "number" },
+        "maxInputTokens": { "type": "number" },
+        "maxOutputTokens": { "type": "number" },
+        "maxDurationSeconds": { "type": "number" },
+        "maxQueueDepth": { "type": "number" },
+        "windowResetAt": {
+          "type": ["string", "number"],
+          "description": "ISO timestamp or Unix timestamp for the window reset."
+        },
+        "returnsCached": {
+          "type": "boolean",
+          "description": "For resource-dedup limits: repeat requests return the cached result as a 200 instead of a 429."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable explanation."
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schema/refusal-429.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gracefulboundaries.dev/schema/refusal-429.schema.json",
+  "title": "Graceful Boundaries 429 refusal response",
+  "description": "Structured refusal shape for limit-class responses (429). Extends the core refusal shape with the fields Level 1 requires on rate-limit refusals. Spec: https://gracefulboundaries.dev/spec",
+  "$ref": "https://gracefulboundaries.dev/schema/refusal.schema.json",
+  "required": ["error", "detail", "why", "limit", "retryAfterSeconds"]
+}

package/schema/refusal.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gracefulboundaries.dev/schema/refusal.schema.json",
+  "title": "Graceful Boundaries non-success response",
+  "description": "Core structured refusal shape for all non-success HTTP responses (400, 401, 403, 404, 405, 410, 422, 429, 500, 502, 503, 504) per Graceful Boundaries. Spec: https://gracefulboundaries.dev/spec",
+  "type": "object",
+  "required": ["error", "detail", "why"],
+  "properties": {
+    "error": {
+      "type": "string",
+      "pattern": "^[a-z0-9_]+$",
+      "description": "Stable machine-parseable error category in snake_case, e.g. rate_limit_exceeded, invalid_input, not_found."
+    },
+    "detail": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable explanation of what happened and how to proceed."
+    },
+    "why": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The security, policy, or operational reason this response exists. Must explain the purpose, not restate the error."
+    },
+    "limit": {
+      "type": "string",
+      "description": "The limit that was exceeded, in human-readable form. Required for 429 responses (see refusal-429.schema.json)."
+    },
+    "retryAfterSeconds": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Seconds until the caller can retry. Required for 429 responses; optional for availability errors."
+    },
+    "limitId": {
+      "type": "string",
+      "description": "Stable identifier for the specific limit exceeded."
+    },
+    "limitType": {
+      "type": "string",
+      "description": "Type of the limit exceeded, such as ip-rate or cost-limit."
+    },
+    "scope": {
+      "type": "string",
+      "description": "Subject of the exceeded limit, such as ip, key, user, resource, or global."
+    },
+    "windowResetAt": {
+      "type": ["string", "number"],
+      "description": "ISO timestamp or Unix timestamp for the window reset."
+    },
+    "cached": {
+      "type": "boolean",
+      "description": "Whether a cached result is available."
+    },
+    "cachedResultUrl": {
+      "type": "string",
+      "description": "URL to retrieve the cached result. Must be a relative path or same-origin absolute URL (SC-6)."
+    },
+    "alternativeEndpoint": {
+      "type": "string",
+      "description": "A different endpoint that may serve the need. Must be a relative path or same-origin absolute URL (SC-6)."
+    },
+    "upgradeUrl": {
+      "type": "string",
+      "description": "Where to get higher limits."
+    },
+    "humanUrl": {
+      "type": "string",
+      "description": "Browser-friendly URL for human follow-up."
+    },
+    "field": {
+      "type": "string",
+      "description": "Which input field failed validation (input class)."
+    },
+    "expected": {
+      "type": "string",
+      "description": "What valid input looks like, stated positively (SC-3)."
+    },
+    "allowedMethods": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Which HTTP methods are accepted (405 responses)."
+    },
+    "authUrl": {
+      "type": "string",
+      "description": "Where to obtain credentials (access class)."
+    },
+    "scanAvailable": {
+      "type": "boolean",
+      "description": "Whether the caller can create the missing resource (not-found class)."
+    },
+    "scanUrl": {
+      "type": "string",
+      "description": "Endpoint to create the missing resource. Not a trust bypass (SC-8)."
+    },
+    "statusUrl": {
+      "type": "string",
+      "description": "Status page or health check endpoint (availability class)."
+    }
+  },
+  "additionalProperties": true
+}