@affordances/protocol 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @affordances/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Affordances protocol: TypeScript types and zod schemas for graphs, calls, deltas, and the site index, the JSON Schemas generated from them, the protocol constants, and the normative `spec.md`. The other Affordances packages import their types from here.
+
+```bash
+vlt install @affordances/protocol
+```
+
+```ts
+import { Delta, Graph, MEDIA_TYPE } from '@affordances/protocol'
+
+const response = await fetch('https://store.example.com/products/tee', {
+  headers: { accept: MEDIA_TYPE },
+})
+const graph = Graph.parse(await response.json())
+```
+
+The JSON Schemas are at `@affordances/protocol/schemas/*.json`, example documents at `@affordances/protocol/fixtures/*`, and the spec at `@affordances/protocol/spec.md`.
+
+Read the protocol: [https://github.com/vltpkg/affordances/blob/main/apps/docs/content/protocol.mdx](https://github.com/vltpkg/affordances/blob/main/apps/docs/content/protocol.mdx)

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+import { z } from "zod";
+export declare const PROTOCOL_VERSION = "0";
+export declare const MEDIA_TYPE = "application/vnd.affordances+json";
+export declare const LINK_REL = "affordances";
+export declare const WELL_KNOWN_PATH = "/.well-known/affordances.json";
+export declare const Expose: z.ZodEnum<{
+  confirm: "confirm";
+  public: "public";
+  session: "session";
+}>;
+export declare const ActionDescriptor: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodString;
+  input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  expose: z.ZodEnum<{
+    confirm: "confirm";
+    public: "public";
+    session: "session";
+  }>;
+  guard: z.ZodOptional<z.ZodString>;
+  available: z.ZodBoolean;
+  reason: z.ZodOptional<z.ZodString>;
+  effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  readOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const NavItem: z.ZodObject<{
+  to: z.ZodString;
+  label: z.ZodOptional<z.ZodString>;
+  when: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const Graph: z.ZodObject<{
+  v: z.ZodLiteral<"0">;
+  page: z.ZodString;
+  route: z.ZodString;
+  entities: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  actions: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    expose: z.ZodEnum<{
+      confirm: "confirm";
+      public: "public";
+      session: "session";
+    }>;
+    guard: z.ZodOptional<z.ZodString>;
+    available: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+    effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+  nav: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    to: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  md: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const Call: z.ZodObject<{
+  action: z.ZodString;
+  input: z.ZodOptional<z.ZodUnknown>;
+  confirm: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const ErrorCode: z.ZodEnum<{
+  confirm_required: "confirm_required";
+  internal: "internal";
+  invalid_input: "invalid_input";
+  not_found: "not_found";
+  rate_limited: "rate_limited";
+  unauthorized: "unauthorized";
+  unavailable: "unavailable";
+}>;
+export declare const Delta: z.ZodObject<{
+  ok: z.ZodBoolean;
+  changed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  output: z.ZodOptional<z.ZodUnknown>;
+  actionsAdded: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    expose: z.ZodEnum<{
+      confirm: "confirm";
+      public: "public";
+      session: "session";
+    }>;
+    guard: z.ZodOptional<z.ZodString>;
+    available: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+    effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>>;
+  actionsRemoved: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  redirect: z.ZodOptional<z.ZodString>;
+  message: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodObject<{
+    code: z.ZodEnum<{
+      confirm_required: "confirm_required";
+      internal: "internal";
+      invalid_input: "invalid_input";
+      not_found: "not_found";
+      rate_limited: "rate_limited";
+      unauthorized: "unauthorized";
+      unavailable: "unavailable";
+    }>;
+    message: z.ZodString;
+    issues: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const AuthMode: z.ZodEnum<{
+  bearer: "bearer";
+  cookie: "cookie";
+}>;
+export declare const ActionSummary: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodString;
+  input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  expose: z.ZodEnum<{
+    confirm: "confirm";
+    public: "public";
+    session: "session";
+  }>;
+  guard: z.ZodOptional<z.ZodString>;
+  effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  readOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const SiteIndex: z.ZodObject<{
+  v: z.ZodLiteral<"0">;
+  name: z.ZodOptional<z.ZodString>;
+  routes: z.ZodArray<z.ZodObject<{
+    route: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    actions: z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      description: z.ZodString;
+      input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      expose: z.ZodEnum<{
+        confirm: "confirm";
+        public: "public";
+        session: "session";
+      }>;
+      guard: z.ZodOptional<z.ZodString>;
+      effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      readOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  auth: z.ZodArray<z.ZodEnum<{
+    bearer: "bearer";
+    cookie: "cookie";
+  }>>;
+  mcp: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Expose = z.infer<typeof Expose>;
+export type ActionDescriptor = z.infer<typeof ActionDescriptor>;
+export type NavItem = z.infer<typeof NavItem>;
+export type Graph = z.infer<typeof Graph>;
+export type Call = z.infer<typeof Call>;
+export type ErrorCode = z.infer<typeof ErrorCode>;
+export type Delta = z.infer<typeof Delta>;
+export type AuthMode = z.infer<typeof AuthMode>;
+export type ActionSummary = z.infer<typeof ActionSummary>;
+export type SiteIndex = z.infer<typeof SiteIndex>;
+export declare const jsonSchemas: {
+  graph: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    v: z.ZodLiteral<"0">;
+    page: z.ZodString;
+    route: z.ZodString;
+    entities: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    actions: z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      description: z.ZodString;
+      input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      expose: z.ZodEnum<{
+        confirm: "confirm";
+        public: "public";
+        session: "session";
+      }>;
+      guard: z.ZodOptional<z.ZodString>;
+      available: z.ZodBoolean;
+      reason: z.ZodOptional<z.ZodString>;
+      effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      readOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    nav: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      to: z.ZodString;
+      label: z.ZodOptional<z.ZodString>;
+      when: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    md: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  call: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    action: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+  delta: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    ok: z.ZodBoolean;
+    changed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    output: z.ZodOptional<z.ZodUnknown>;
+    actionsAdded: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      description: z.ZodString;
+      input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      expose: z.ZodEnum<{
+        confirm: "confirm";
+        public: "public";
+        session: "session";
+      }>;
+      guard: z.ZodOptional<z.ZodString>;
+      available: z.ZodBoolean;
+      reason: z.ZodOptional<z.ZodString>;
+      effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      readOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    actionsRemoved: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    redirect: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+      code: z.ZodEnum<{
+        confirm_required: "confirm_required";
+        internal: "internal";
+        invalid_input: "invalid_input";
+        not_found: "not_found";
+        rate_limited: "rate_limited";
+        unauthorized: "unauthorized";
+        unavailable: "unavailable";
+      }>;
+      message: z.ZodString;
+      issues: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  'site-index': z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    v: z.ZodLiteral<"0">;
+    name: z.ZodOptional<z.ZodString>;
+    routes: z.ZodArray<z.ZodObject<{
+      route: z.ZodString;
+      description: z.ZodOptional<z.ZodString>;
+      actions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        expose: z.ZodEnum<{
+          confirm: "confirm";
+          public: "public";
+          session: "session";
+        }>;
+        guard: z.ZodOptional<z.ZodString>;
+        effects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    auth: z.ZodArray<z.ZodEnum<{
+      bearer: "bearer";
+      cookie: "cookie";
+    }>>;
+    mcp: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+};

package/dist/index.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+// src/schema.ts
+const PROTOCOL_VERSION = "0";
+const MEDIA_TYPE = "application/vnd.affordances+json";
+const LINK_REL = "affordances";
+const WELL_KNOWN_PATH = "/.well-known/affordances.json";
+const JSONSchema = z.record(z.string(), z.unknown()).meta({ description: "A JSON Schema object" });
+const Expose = z.enum([
+	"public",
+	"session",
+	"confirm"
+]);
+const ActionDescriptor = z.object({
+	name: z.string().min(1).describe("Stable, unique per route"),
+	description: z.string(),
+	input: JSONSchema,
+	output: JSONSchema.optional(),
+	expose: Expose,
+	guard: z.string().optional().describe("Human-readable precondition"),
+	available: z.boolean().describe("The guard, evaluated for this request"),
+	reason: z.string().optional().describe("Why the action is unavailable"),
+	effects: z.array(z.string()).optional().describe("Entity keys this action changes"),
+	readOnly: z.boolean().optional()
+}).meta({ id: "ActionDescriptor" });
+const NavItem = z.object({
+	to: z.string(),
+	label: z.string().optional(),
+	when: z.string().optional()
+});
+const Graph = z.object({
+	v: z.literal("0"),
+	page: z.string().describe("Concrete path, e.g. /products/tee"),
+	route: z.string().describe("Route pattern, e.g. /products/[slug]"),
+	entities: z.record(z.string(), z.unknown()),
+	actions: z.array(ActionDescriptor),
+	nav: z.array(NavItem).optional(),
+	md: z.string().optional().describe("Optional Markdown alternative of the page content")
+}).meta({ id: "Graph" });
+const Call = z.object({
+	action: z.string().min(1),
+	input: z.unknown().optional(),
+	confirm: z.boolean().optional()
+}).meta({ id: "Call" });
+const ErrorCode = z.enum([
+	"not_found",
+	"invalid_input",
+	"unauthorized",
+	"confirm_required",
+	"unavailable",
+	"rate_limited",
+	"internal"
+]);
+const Delta = z.object({
+	ok: z.boolean(),
+	changed: z.record(z.string(), z.unknown()).optional().describe("Only the action's effects keys"),
+	output: z.unknown().optional().describe("The action's return value, matching its output schema"),
+	actionsAdded: z.array(ActionDescriptor).optional(),
+	actionsRemoved: z.array(z.string()).optional(),
+	redirect: z.string().optional(),
+	message: z.string().optional(),
+	error: z.object({
+		code: ErrorCode,
+		message: z.string(),
+		issues: z.unknown().optional()
+	}).optional()
+}).meta({ id: "Delta" });
+const AuthMode = z.enum(["cookie", "bearer"]);
+const ActionSummary = ActionDescriptor.omit({
+	available: true,
+	reason: true
+}).meta({ id: "ActionSummary" });
+const SiteIndex = z.object({
+	v: z.literal("0"),
+	name: z.string().optional(),
+	routes: z.array(z.object({
+		route: z.string(),
+		description: z.string().optional().describe("What the page is for, in one line"),
+		actions: z.array(ActionSummary)
+	})),
+	auth: z.array(AuthMode),
+	mcp: z.string().optional().describe("URL of an MCP endpoint for this site")
+}).meta({ id: "SiteIndex" });
+// src/json-schema.ts
+const jsonSchemas = {
+	graph: z.toJSONSchema(Graph),
+	call: z.toJSONSchema(Call),
+	delta: z.toJSONSchema(Delta),
+	"site-index": z.toJSONSchema(SiteIndex)
+};
+export { ActionDescriptor, ActionSummary, AuthMode, Call, Delta, ErrorCode, Expose, Graph, LINK_REL, MEDIA_TYPE, NavItem, PROTOCOL_VERSION, SiteIndex, WELL_KNOWN_PATH, jsonSchemas };

package/fixtures/invalid/call.no-action.json

@@ -0,0 +1 @@
+{ "input": {} }

package/fixtures/invalid/delta.unknown-code.json

@@ -0,0 +1 @@
+{ "ok": false, "error": { "code": "teapot", "message": "no" } }

package/fixtures/invalid/graph.bad-expose.json

@@ -0,0 +1,9 @@
+{
+  "v": "0",
+  "page": "/",
+  "route": "/",
+  "entities": {},
+  "actions": [
+    { "name": "x", "description": "", "input": {}, "expose": "everyone", "available": true }
+  ]
+}

package/fixtures/invalid/graph.wrong-version.json

@@ -0,0 +1 @@
+{ "v": "1", "page": "/", "route": "/", "entities": {}, "actions": [] }

package/fixtures/valid/call.place-order.json

@@ -0,0 +1 @@
+{ "action": "placeOrder", "input": { "shipping": "standard" }, "confirm": true }

package/fixtures/valid/delta.add-to-cart.json

@@ -0,0 +1,5 @@
+{
+  "ok": true,
+  "changed": { "cart": { "count": 2, "subtotal": { "amount": 6000, "currency": "USD" } } },
+  "message": "Added Heavyweight Tee (M) to your cart"
+}

package/fixtures/valid/delta.errors.json

@@ -0,0 +1,28 @@
+[
+  {
+    "ok": false,
+    "error": { "code": "not_found", "message": "No action named addToKart on /products/[slug]" }
+  },
+  {
+    "ok": false,
+    "error": {
+      "code": "invalid_input",
+      "message": "Input does not match the action's schema",
+      "issues": [{ "path": ["quantity"], "message": "Expected a number greater than 0" }]
+    }
+  },
+  { "ok": false, "error": { "code": "unauthorized", "message": "This action needs a session" } },
+  {
+    "ok": false,
+    "error": {
+      "code": "confirm_required",
+      "message": "Place an order for 2 items totalling $60.00"
+    }
+  },
+  { "ok": false, "error": { "code": "unavailable", "message": "Size L is out of stock" } },
+  {
+    "ok": false,
+    "error": { "code": "rate_limited", "message": "Too many calls to addToCart; retry in 10s" }
+  },
+  { "ok": false, "error": { "code": "internal", "message": "Something went wrong" } }
+]

package/fixtures/valid/graph.product.json

@@ -0,0 +1,51 @@
+{
+  "v": "0",
+  "page": "/products/heavyweight-tee",
+  "route": "/products/[slug]",
+  "entities": {
+    "product": {
+      "slug": "heavyweight-tee",
+      "name": "Heavyweight Tee",
+      "price": { "amount": 4800, "currency": "USD" },
+      "variants": [
+        { "sku": "TEE-BLK-M", "color": "black", "size": "M", "stock": 12 },
+        { "sku": "TEE-BLK-L", "color": "black", "size": "L", "stock": 0 }
+      ]
+    },
+    "cart": { "count": 1, "subtotal": { "amount": 1200, "currency": "USD" } }
+  },
+  "actions": [
+    {
+      "name": "addToCart",
+      "description": "Add a product variant to the cart",
+      "input": {
+        "type": "object",
+        "properties": {
+          "sku": { "type": "string" },
+          "quantity": { "type": "integer", "minimum": 1 }
+        },
+        "required": ["sku"]
+      },
+      "expose": "session",
+      "guard": "The variant is in stock",
+      "available": true,
+      "effects": ["cart"]
+    },
+    {
+      "name": "notifyWhenInStock",
+      "description": "Email me when a sold-out variant is back",
+      "input": {
+        "type": "object",
+        "properties": { "sku": { "type": "string" } },
+        "required": ["sku"]
+      },
+      "expose": "session",
+      "available": false,
+      "reason": "Sign in to get notified"
+    }
+  ],
+  "nav": [
+    { "to": "/cart", "label": "Cart" },
+    { "to": "/checkout", "label": "Checkout", "when": "cart.count > 0" }
+  ]
+}

package/fixtures/valid/site-index.json

@@ -0,0 +1,33 @@
+{
+  "v": "0",
+  "name": "Acme Store",
+  "routes": [
+    {
+      "route": "/products/[slug]",
+      "description": "One product: its variants, prices and stock",
+      "actions": [
+        {
+          "name": "addToCart",
+          "description": "Add a product variant to the cart",
+          "input": {
+            "type": "object",
+            "properties": {
+              "sku": { "type": "string" },
+              "quantity": { "type": "integer", "minimum": 1 }
+            },
+            "required": ["sku"]
+          },
+          "expose": "public",
+          "guard": "The variant is in stock",
+          "effects": ["cart"]
+        }
+      ]
+    },
+    {
+      "route": "/account/orders",
+      "description": "Orders placed in this session, newest first",
+      "actions": []
+    }
+  ],
+  "auth": ["cookie", "bearer"]
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@affordances/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Affordances protocol: types, JSON Schemas, and the spec",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/affordances.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "fixtures",
+    "spec.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./fixtures/*": "./fixtures/*",
+    "./spec.md": "./spec.md"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "schemas": "node scripts/schemas.ts"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  }
+}

package/schemas/call.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Call",
+  "$defs": {
+    "Call": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "input": {},
+        "confirm": {
+          "type": "boolean"
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/delta.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Delta",
+  "$defs": {
+    "Delta": {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "changed": {
+          "description": "Only the action's effects keys",
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "output": {
+          "description": "The action's return value, matching its output schema"
+        },
+        "actionsAdded": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ActionDescriptor"
+          }
+        },
+        "actionsRemoved": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "redirect": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": [
+                "not_found",
+                "invalid_input",
+                "unauthorized",
+                "confirm_required",
+                "unavailable",
+                "rate_limited",
+                "internal"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "issues": {}
+          },
+          "required": ["code", "message"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["ok"],
+      "additionalProperties": false
+    },
+    "ActionDescriptor": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable, unique per route"
+        },
+        "description": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "output": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "expose": {
+          "type": "string",
+          "enum": ["public", "session", "confirm"]
+        },
+        "guard": {
+          "description": "Human-readable precondition",
+          "type": "string"
+        },
+        "available": {
+          "type": "boolean",
+          "description": "The guard, evaluated for this request"
+        },
+        "reason": {
+          "description": "Why the action is unavailable",
+          "type": "string"
+        },
+        "effects": {
+          "description": "Entity keys this action changes",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "readOnly": {
+          "type": "boolean"
+        }
+      },
+      "required": ["name", "description", "input", "expose", "available"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/graph.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Graph",
+  "$defs": {
+    "Graph": {
+      "type": "object",
+      "properties": {
+        "v": {
+          "type": "string",
+          "const": "0"
+        },
+        "page": {
+          "type": "string",
+          "description": "Concrete path, e.g. /products/tee"
+        },
+        "route": {
+          "type": "string",
+          "description": "Route pattern, e.g. /products/[slug]"
+        },
+        "entities": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "actions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ActionDescriptor"
+          }
+        },
+        "nav": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "to": {
+                "type": "string"
+              },
+              "label": {
+                "type": "string"
+              },
+              "when": {
+                "type": "string"
+              }
+            },
+            "required": ["to"],
+            "additionalProperties": false
+          }
+        },
+        "md": {
+          "description": "Optional Markdown alternative of the page content",
+          "type": "string"
+        }
+      },
+      "required": ["v", "page", "route", "entities", "actions"],
+      "additionalProperties": false
+    },
+    "ActionDescriptor": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable, unique per route"
+        },
+        "description": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "output": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "expose": {
+          "type": "string",
+          "enum": ["public", "session", "confirm"]
+        },
+        "guard": {
+          "description": "Human-readable precondition",
+          "type": "string"
+        },
+        "available": {
+          "type": "boolean",
+          "description": "The guard, evaluated for this request"
+        },
+        "reason": {
+          "description": "Why the action is unavailable",
+          "type": "string"
+        },
+        "effects": {
+          "description": "Entity keys this action changes",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "readOnly": {
+          "type": "boolean"
+        }
+      },
+      "required": ["name", "description", "input", "expose", "available"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/site-index.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/SiteIndex",
+  "$defs": {
+    "SiteIndex": {
+      "type": "object",
+      "properties": {
+        "v": {
+          "type": "string",
+          "const": "0"
+        },
+        "name": {
+          "type": "string"
+        },
+        "routes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "route": {
+                "type": "string"
+              },
+              "description": {
+                "description": "What the page is for, in one line",
+                "type": "string"
+              },
+              "actions": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/ActionSummary"
+                }
+              }
+            },
+            "required": ["route", "actions"],
+            "additionalProperties": false
+          }
+        },
+        "auth": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["cookie", "bearer"]
+          }
+        },
+        "mcp": {
+          "description": "URL of an MCP endpoint for this site",
+          "type": "string"
+        }
+      },
+      "required": ["v", "routes", "auth"],
+      "additionalProperties": false
+    },
+    "ActionSummary": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable, unique per route"
+        },
+        "description": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "output": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "A JSON Schema object"
+        },
+        "expose": {
+          "type": "string",
+          "enum": ["public", "session", "confirm"]
+        },
+        "guard": {
+          "description": "Human-readable precondition",
+          "type": "string"
+        },
+        "effects": {
+          "description": "Entity keys this action changes",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "readOnly": {
+          "type": "boolean"
+        }
+      },
+      "required": ["name", "description", "input", "expose"],
+      "additionalProperties": false
+    }
+  }
+}

package/spec.md

@@ -0,0 +1,161 @@
+# Affordances protocol, version 0
+
+Affordances lets an agent read and operate a web page through the same URL a person uses, with the same session. A page answers in HTML for browsers and in JSON for agents. The JSON lists what the page shows (entities), what can be done there (actions), and where to go next (nav). Calling an action returns a delta: the parts of the page that changed.
+
+This document is normative. The key words "must", "must not", "should", and "may" are used as in RFC 2119. The JSON Schemas in `schemas/` are generated from the same source as the TypeScript types and are authoritative for shapes.
+
+## Media type
+
+All Affordances documents use `application/vnd.affordances+json`. A server must not return an Affordances document for a request that did not ask for one.
+
+## Discovery
+
+**Per page.** A client requests the page's own URL with `Accept: application/vnd.affordances+json`. The server responds with a [graph](#graph) for that page, or a `not_found` [delta](#delta) with status `404` if the page has no Affordances graph.
+
+HTML responses for pages with a graph should advertise it in both places:
+
+```http
+Link: <?affordances=1>; rel="affordances"
+```
+
+```html
+<link rel="affordances" href="?affordances=1" />
+```
+
+`?affordances=1` is an alias for the `Accept` header, for clients that cannot set headers. A server that supports it must treat `GET <url>?affordances=1` like `GET <url>` with the Affordances `Accept` header, and must leave `affordances` out of the `searchParams` it gives the page's state.
+
+**Per site.** `GET /.well-known/affordances.json` returns a [site index](#site-index): the protocol version, the route patterns that have graphs and their action names, the supported auth modes, and optionally an MCP endpoint.
+
+A shared cache must never serve one representation for the other: graphs send `Vary: Accept` and `Cache-Control: private, no-store`, and a server must make sure cached HTML is keyed on `Accept` too (with `Vary: Accept`, or by routing Affordances requests before the cache, as `@affordances/next` does with rewrites).
+
+## Graph
+
+```ts
+type Graph = {
+  v: '0'
+  page: string // concrete path: /products/heavyweight-tee
+  route: string // pattern: /products/[slug]
+  entities: Record<string, unknown>
+  actions: ActionDescriptor[]
+  nav?: { to: string; label?: string; when?: string }[]
+  md?: string
+}
+```
+
+- `entities` is the page's state, keyed by name. It must not contain anything the page would not show the same user in HTML.
+- `actions` lists every action on the route that the requester may know about. Actions the requester can't call right now are still listed, with `available: false` and a `reason`.
+- `nav` lists links an agent can follow. `when` is a human-readable condition.
+- `md` is an optional Markdown rendering of the page's content.
+- A graph should stay small. About 2,000 tokens is a good ceiling, and large collections should be summarized in `entities`.
+
+### Action descriptor
+
+```ts
+type ActionDescriptor = {
+  name: string // unique per route, stable across releases
+  description: string
+  input: JSONSchema
+  output?: JSONSchema
+  expose: 'public' | 'session' | 'confirm'
+  guard?: string // human-readable precondition
+  available: boolean // the guard, evaluated for this request
+  reason?: string // why available is false
+  effects?: string[] // entity keys the action changes
+  readOnly?: boolean
+}
+```
+
+`expose` says who may call an action:
+
+| `expose`  | Caller                                                                               |
+| --------- | ------------------------------------------------------------------------------------ |
+| `public`  | anyone                                                                               |
+| `session` | an authenticated session, by cookie or bearer token                                  |
+| `confirm` | a session, and the call must carry `confirm: true` after the user has seen a summary |
+
+An action with no `expose` is not part of the protocol. It must not appear in graphs and must not be callable.
+
+## Call
+
+```http
+POST <page-url>
+Content-Type: application/vnd.affordances+json
+
+{ "action": "addToCart", "input": { "sku": "TEE-BLK-M" } }
+```
+
+```ts
+type Call = { action: string; input?: unknown; confirm?: boolean }
+```
+
+The server processes a call in this order, and stops at the first failure:
+
+1. Resolve the action by name on the page's route. Failure: `not_found`.
+2. Check the CSRF rule below and `expose` against the caller. Failure: `unauthorized`.
+3. Apply the rate limit. Failure: `rate_limited`.
+4. Validate `input` against the action's input schema. Failure: `invalid_input`, with `issues`.
+5. Evaluate the guard. Failure: `unavailable`, with the guard's reason as `message`.
+6. For `confirm` actions without `confirm: true`: `confirm_required`, with a summary of what will happen as `message`, written for the person who approves it. Nothing runs.
+7. Run the action, reload the page's state, and respond with a delta.
+
+## Delta
+
+```ts
+type Delta = {
+  ok: boolean
+  changed?: Record<string, unknown>
+  output?: unknown
+  actionsAdded?: ActionDescriptor[]
+  actionsRemoved?: string[]
+  redirect?: string
+  message?: string
+  error?: { code: ErrorCode; message: string; issues?: unknown }
+}
+```
+
+- `changed` holds the new value of each entity in the action's `effects`. When an action declares no effects, `changed` holds every top-level entity whose value differs after the action ran.
+- `output` is the action's return value, described by the descriptor's `output` schema when it has one.
+- `actionsAdded` and `actionsRemoved` describe changes to the action list, including availability changes. An action whose `available` flipped appears in `actionsAdded` with its new descriptor.
+- `redirect` is a path the person would have been sent to. The agent should request it next.
+- `message` is a short sentence suitable to repeat to the user.
+
+### Error codes
+
+| Code               | HTTP | Meaning                                                 |
+| ------------------ | ---- | ------------------------------------------------------- |
+| `not_found`        | 404  | No such route or action                                 |
+| `invalid_input`    | 422  | `input` failed the schema; `issues` says where          |
+| `unauthorized`     | 401  | The caller may not call this action                     |
+| `confirm_required` | 409  | Resend with `confirm: true` after showing `message`     |
+| `unavailable`      | 409  | The guard failed; `message` says why                    |
+| `rate_limited`     | 429  | Too many calls; the response should carry `Retry-After` |
+| `internal`         | 500  | The action threw; `message` must not leak internals     |
+
+## Site index
+
+```ts
+type SiteIndex = {
+  v: '0'
+  name?: string
+  routes: { route: string; description?: string; actions: ActionSummary[] }[]
+  auth: ('cookie' | 'bearer')[]
+  mcp?: string
+}
+
+// an action descriptor without this request's availability (no `available`, no `reason`)
+type ActionSummary = Omit<ActionDescriptor, 'available' | 'reason'>
+```
+
+The index is enough to plan a task and to call an action without opening its page first: an agent that knows the route and the input can `POST` straight to a concrete URL of that route. It still gets `unavailable` or `unauthorized` if the guard or `expose` says no. Each route's `description` is one line on what the page is for. Input schemas may omit `$schema`; they are JSON Schema 2020-12.
+
+## Security
+
+- Default deny. Only actions that declare `expose` are reachable.
+- A call that authenticates by cookie must carry an `Origin` header that matches the site. A call with `Authorization: Bearer` is exempt. A server must not rely on its framework's server-action protections for Affordances calls.
+- `confirm` actions must not run without `confirm: true`. Clients acting for a person should show `message` and get approval first.
+- Input is validated before the guard runs, and the guard runs before the action.
+- URLs must not carry personal data. A graph must not include data that the HTML page would not show to the same user.
+
+## Versioning
+
+`v` is the protocol's major version. A breaking change ships as a new major version. Additive changes, such as new optional fields, may ship within a major version, and clients must ignore fields they don't recognize. Packages declare the range of majors they support.