@jarenjs/contract 0.43.1

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@jarenjs/contract",
+  "private": false,
+  "version": "0.43.1",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "bin": {
+    "jaren-contract": "./src/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./http": {
+      "types": "./dist/types/http/serve.d.ts",
+      "default": "./src/http/serve.js"
+    },
+    "./fetch": {
+      "types": "./dist/types/adapters/fetch.d.ts",
+      "default": "./src/adapters/fetch.js"
+    },
+    "./node": {
+      "types": "./dist/types/adapters/node.d.ts",
+      "default": "./src/adapters/node.js"
+    },
+    "./ledger": {
+      "types": "./dist/types/ledger.d.ts",
+      "default": "./src/ledger.js"
+    },
+    "./diff": {
+      "types": "./dist/types/diff.d.ts",
+      "default": "./src/diff.js"
+    },
+    "./client": {
+      "types": "./dist/types/client/http.d.ts",
+      "default": "./src/client/http.js"
+    },
+    "./local": {
+      "types": "./dist/types/local/index.d.ts",
+      "default": "./src/local/index.js"
+    },
+    "./port": {
+      "types": "./dist/types/port/serve.d.ts",
+      "default": "./src/port/serve.js"
+    },
+    "./stream": {
+      "types": "./dist/types/stream/server.d.ts",
+      "default": "./src/stream/server.js"
+    },
+    "./app": {
+      "types": "./dist/types/app/index.d.ts",
+      "default": "./src/app/index.js"
+    },
+    "./project": {
+      "types": "./dist/types/project/index.d.ts",
+      "default": "./src/project/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "docs/",
+    "schemas/"
+  ],
+  "description": "Operation contracts for the Jaren suite: the jaren-contract document declares JSON-in/JSON-out operations with kind, policy and an HTTP binding, compiled once into per-operation validators, transport normalizers and a static-beats-variable path matcher, served over HTTP through a total dispatch pipeline with fetch and node adapters, in-process through the local binding and over MessagePort/Worker/BroadcastChannel through the port binding with collision-free request ids, called through clients that resolve JSON outcomes, bound to @jarenjs/app documents through generated task slots and one effect, and projected to a public subset, OpenAPI 3.1, TypeScript, Markdown and AI tool definitions with a jaren-contract CLI that checks them in CI",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "packages/contract"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "json-schema",
+    "contract",
+    "api",
+    "rest",
+    "router",
+    "openapi",
+    "typescript",
+    "idempotency",
+    "client",
+    "outcome"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/validate": "^0.43.1",
+    "@jarenjs/emit": "^0.43.1"
+  }
+}

package/schemas/jaren-contract-port.draft-07.schema.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-contract-port/0.1/draft-07",
+  "title": "Jaren contract port frame 0.1",
+  "description": "The frame grammar of the port binding (packages/contract/docs/CONTRACT-FORMAT.md §16): every message the binding puts on a MessagePort, Worker or BroadcastChannel is one of these six JSON-safe plain objects (request/response/cancel, and the stream family: subscribe/unsubscribe from a client, push events from a server), marked jaren: \"contract/0.1\" so contract traffic is distinguishable by shape from anything else sharing the channel. A request id is \"<clientId>:<seq>\" — the client id unique per client instance — so two clients on one channel can never cross-settle; the request members attempt and key are reserved and ignored by servers of this version.",
+  "oneOf": [
+    {
+      "$ref": "#/definitions/request"
+    },
+    {
+      "$ref": "#/definitions/response"
+    },
+    {
+      "$ref": "#/definitions/cancel"
+    },
+    {
+      "$ref": "#/definitions/subscribe"
+    },
+    {
+      "$ref": "#/definitions/unsubscribe"
+    },
+    {
+      "$ref": "#/definitions/push"
+    }
+  ],
+  "definitions": {
+    "marker": {
+      "description": "The protocol and its version.",
+      "const": "contract/0.1"
+    },
+    "id": {
+      "description": "A request id: the client id (no colon), a colon, the per-client sequence number.",
+      "type": "string",
+      "pattern": "^[^:]+:[1-9][0-9]*$"
+    },
+    "request": {
+      "description": "A client's request: one operation invocation. input is the whole input object, or null for an input-less operation.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "op",
+        "input"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "id": {
+          "$ref": "#/definitions/id"
+        },
+        "op": {
+          "description": "The operation id, as declared in the contract.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+        },
+        "input": true,
+        "attempt": true,
+        "key": {
+          "description": "Reserved: an idempotency key. The port binding does not carry idempotency (capabilities say so); a server of this version ignores it.",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "response": {
+      "description": "A server's answer to one request id, success or error, always carrying the server trace.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "ok",
+        "trace"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "id": {
+          "$ref": "#/definitions/id"
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "value": true,
+        "error": {
+          "$ref": "#/definitions/error"
+        },
+        "trace": {
+          "description": "The server's per-request trace id (meta.trace on the client).",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "error": false
+          }
+        },
+        {
+          "required": [
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "value": false
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "error": {
+      "description": "The error envelope of a failed response: a declared error code (lowercase) or a JC2xxx taxonomy/binding code; details present only when the failure carries some.",
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^([a-z][a-z0-9-]*|JC[0-9]{4})$"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": true,
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "cancel": {
+      "description": "A client's cancellation of one request id: aborts the server-side signal. An optimization — the id scoping is the guarantee — and never answered.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "cancel"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "cancel": {
+          "$ref": "#/definitions/id"
+        }
+      },
+      "additionalProperties": false
+    },
+    "subscribe": {
+      "description": "A client's subscription of one subscribe operation: opens a stream under the id. input is the whole input object, or null for an input-less operation; lastSeq, when present, asks to resume after that seq.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "subscribe",
+        "op",
+        "input"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "subscribe": {
+          "$ref": "#/definitions/id"
+        },
+        "op": {
+          "description": "The operation id, as declared in the contract.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+        },
+        "input": true,
+        "lastSeq": {
+          "description": "The last seq this client delivered; the server replays after it or answers a fresh snapshot with resumed: false.",
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "unsubscribe": {
+      "description": "A client's release of one stream id. Never answered.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "unsubscribe"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "unsubscribe": {
+          "$ref": "#/definitions/id"
+        }
+      },
+      "additionalProperties": false
+    },
+    "push": {
+      "description": "A server's stream event for one subscription id: snapshot data is { value, resumed }, patch data the LIVE emission { patch, seq }, error data the wire error record, end data { reason }. seq is the event's seq; error and end carry the last delivered one.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "event",
+        "seq",
+        "data"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/definitions/marker"
+        },
+        "id": {
+          "$ref": "#/definitions/id"
+        },
+        "event": {
+          "enum": [
+            "snapshot",
+            "patch",
+            "error",
+            "end"
+          ]
+        },
+        "seq": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "data": true
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/jaren-contract-port.schema.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-contract-port/0.1",
+  "title": "Jaren contract port frame 0.1",
+  "description": "The frame grammar of the port binding (packages/contract/docs/CONTRACT-FORMAT.md §16): every message the binding puts on a MessagePort, Worker or BroadcastChannel is one of these six JSON-safe plain objects (request/response/cancel, and the stream family: subscribe/unsubscribe from a client, push events from a server), marked jaren: \"contract/0.1\" so contract traffic is distinguishable by shape from anything else sharing the channel. A request id is \"<clientId>:<seq>\" — the client id unique per client instance — so two clients on one channel can never cross-settle; the request members attempt and key are reserved and ignored by servers of this version.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/request"
+    },
+    {
+      "$ref": "#/$defs/response"
+    },
+    {
+      "$ref": "#/$defs/cancel"
+    },
+    {
+      "$ref": "#/$defs/subscribe"
+    },
+    {
+      "$ref": "#/$defs/unsubscribe"
+    },
+    {
+      "$ref": "#/$defs/push"
+    }
+  ],
+  "$defs": {
+    "marker": {
+      "description": "The protocol and its version.",
+      "const": "contract/0.1"
+    },
+    "id": {
+      "description": "A request id: the client id (no colon), a colon, the per-client sequence number.",
+      "type": "string",
+      "pattern": "^[^:]+:[1-9][0-9]*$"
+    },
+    "request": {
+      "description": "A client's request: one operation invocation. input is the whole input object, or null for an input-less operation.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "op",
+        "input"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "op": {
+          "description": "The operation id, as declared in the contract.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+        },
+        "input": true,
+        "attempt": true,
+        "key": {
+          "description": "Reserved: an idempotency key. The port binding does not carry idempotency (capabilities say so); a server of this version ignores it.",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "response": {
+      "description": "A server's answer to one request id, success or error, always carrying the server trace.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "ok",
+        "trace"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "value": true,
+        "error": {
+          "$ref": "#/$defs/error"
+        },
+        "trace": {
+          "description": "The server's per-request trace id (meta.trace on the client).",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "error": false
+          }
+        },
+        {
+          "required": [
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "value": false
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "error": {
+      "description": "The error envelope of a failed response: a declared error code (lowercase) or a JC2xxx taxonomy/binding code; details present only when the failure carries some.",
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^([a-z][a-z0-9-]*|JC[0-9]{4})$"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": true,
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "cancel": {
+      "description": "A client's cancellation of one request id: aborts the server-side signal. An optimization — the id scoping is the guarantee — and never answered.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "cancel"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "cancel": {
+          "$ref": "#/$defs/id"
+        }
+      },
+      "additionalProperties": false
+    },
+    "subscribe": {
+      "description": "A client's subscription of one subscribe operation: opens a stream under the id. input is the whole input object, or null for an input-less operation; lastSeq, when present, asks to resume after that seq.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "subscribe",
+        "op",
+        "input"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "subscribe": {
+          "$ref": "#/$defs/id"
+        },
+        "op": {
+          "description": "The operation id, as declared in the contract.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+        },
+        "input": true,
+        "lastSeq": {
+          "description": "The last seq this client delivered; the server replays after it or answers a fresh snapshot with resumed: false.",
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "unsubscribe": {
+      "description": "A client's release of one stream id. Never answered.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "unsubscribe"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "unsubscribe": {
+          "$ref": "#/$defs/id"
+        }
+      },
+      "additionalProperties": false
+    },
+    "push": {
+      "description": "A server's stream event for one subscription id: snapshot data is { value, resumed }, patch data the LIVE emission { patch, seq }, error data the wire error record, end data { reason }. seq is the event's seq; error and end carry the last delivered one.",
+      "type": "object",
+      "required": [
+        "jaren",
+        "id",
+        "event",
+        "seq",
+        "data"
+      ],
+      "properties": {
+        "jaren": {
+          "$ref": "#/$defs/marker"
+        },
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "event": {
+          "enum": [
+            "snapshot",
+            "patch",
+            "error",
+            "end"
+          ]
+        },
+        "seq": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "data": true
+      },
+      "additionalProperties": false
+    }
+  }
+}