@cleocode/lafs 1.8.0

package/schemas/v1/envelope.schema.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "title": "LAFS Envelope v1",
+  "type": "object",
+  "required": [
+    "$schema",
+    "_meta",
+    "success",
+    "result"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://lafs.dev/schemas/v1/envelope.schema.json"
+    },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "specVersion",
+        "schemaVersion",
+        "timestamp",
+        "operation",
+        "requestId",
+        "transport",
+        "strict",
+        "mvi",
+        "contextVersion"
+      ],
+      "properties": {
+        "specVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "operation": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "requestId": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 128
+        },
+        "transport": {
+          "type": "string",
+          "enum": ["cli", "http", "grpc", "sdk"]
+        },
+        "strict": {
+          "type": "boolean"
+        },
+        "mvi": {
+          "type": "string",
+          "enum": ["minimal", "standard", "full", "custom"],
+          "description": "Disclosure level: minimal (MVI only), standard (common fields), full (all fields), custom (per _fields parameter)"
+        },
+        "contextVersion": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Session identifier for correlating multi-step agent workflows"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string", "description": "Warning identifier (e.g., DEPRECATED_FIELD)" },
+              "message": { "type": "string", "description": "Human-readable warning" },
+              "deprecated": { "type": "string", "description": "The deprecated feature or field name" },
+              "replacement": { "type": "string", "description": "Suggested replacement, if any" },
+              "removeBy": { "type": "string", "description": "Version when the deprecated feature will be removed" }
+            },
+            "required": ["code", "message"]
+          },
+          "description": "Non-fatal advisory warnings (deprecations, migration hints)"
+        }
+      }
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "result": {
+      "type": ["object", "array", "null"]
+    },
+    "error": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "required": [
+        "code",
+        "message",
+        "category",
+        "retryable",
+        "retryAfterMs",
+        "details"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^E_[A-Z0-9]+_[A-Z0-9_]+$"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "VALIDATION",
+            "AUTH",
+            "PERMISSION",
+            "NOT_FOUND",
+            "CONFLICT",
+            "RATE_LIMIT",
+            "TRANSIENT",
+            "INTERNAL",
+            "CONTRACT",
+            "MIGRATION"
+          ]
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "retryAfterMs": {
+          "type": ["integer", "null"],
+          "minimum": 0
+        },
+        "details": {
+          "type": "object"
+        },
+        "agentAction": {
+          "type": "string",
+          "enum": ["retry", "retry_modified", "escalate", "stop", "wait", "refresh_context", "authenticate"],
+          "description": "Machine-actionable instruction for the consuming agent"
+        },
+        "escalationRequired": {
+          "type": "boolean",
+          "description": "Whether human/owner intervention is required"
+        },
+        "suggestedAction": {
+          "type": "string",
+          "maxLength": 512,
+          "description": "Brief actionable instruction for error recovery"
+        },
+        "docUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Documentation URL for this error type"
+        }
+      }
+    },
+    "page": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["offset", "cursor", "none"]
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "nextCursor": {
+          "type": ["string", "null"],
+          "maxLength": 2048
+        },
+        "hasMore": {
+          "type": "boolean"
+        },
+        "total": {
+          "type": ["integer", "null"],
+          "minimum": 0
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "cursor" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "nextCursor", "hasMore"],
+            "properties": {
+              "mode": true,
+              "nextCursor": true,
+              "hasMore": true,
+              "limit": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "offset" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "limit", "offset", "hasMore"],
+            "properties": {
+              "mode": true,
+              "limit": true,
+              "offset": true,
+              "hasMore": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "none" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode"],
+            "properties": {
+              "mode": true
+            }
+          }
+        }
+      ]
+    },
+    "_extensions": {
+      "type": "object",
+      "description": "Vendor extensions. Keys SHOULD use x- prefix (e.g., x-myvendor-trace-id).",
+      "additionalProperties": true
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "success": { "const": true }
+        }
+      },
+      "then": {
+        "properties": {
+          "error": { "type": "null" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "success": { "const": false }
+        }
+      },
+      "then": {
+        "required": ["error"],
+        "properties": {
+          "error": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "_meta": {
+            "type": "object",
+            "properties": {
+              "strict": { "const": true }
+            }
+          }
+        }
+      },
+      "then": {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": true,
+          "_meta": true,
+          "success": true,
+          "result": true,
+          "error": true,
+          "page": true,
+          "_extensions": true
+        }
+      },
+      "else": {
+        "additionalProperties": true
+      }
+    }
+  ]
+}

package/schemas/v1/error-registry.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0.0",
+  "codes": [
+    {
+      "code": "E_FORMAT_CONFLICT",
+      "category": "CONTRACT",
+      "description": "Mutually exclusive format flags requested",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2,
+      "agentAction": "stop",
+      "typeUri": "https://lafs.dev/errors/v1/format-conflict",
+      "docUrl": "https://lafs.dev/docs/errors/format-conflict"
+    },
+    {
+      "code": "E_VALIDATION_SCHEMA",
+      "category": "VALIDATION",
+      "description": "Input failed schema validation",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2,
+      "agentAction": "retry_modified",
+      "typeUri": "https://lafs.dev/errors/v1/validation-schema",
+      "docUrl": "https://lafs.dev/docs/errors/validation-schema"
+    },
+    {
+      "code": "E_NOT_FOUND_RESOURCE",
+      "category": "NOT_FOUND",
+      "description": "Referenced resource was not found",
+      "retryable": false,
+      "httpStatus": 404,
+      "grpcStatus": "NOT_FOUND",
+      "cliExit": 4,
+      "agentAction": "stop",
+      "typeUri": "https://lafs.dev/errors/v1/not-found-resource",
+      "docUrl": "https://lafs.dev/docs/errors/not-found-resource"
+    },
+    {
+      "code": "E_CONFLICT_VERSION",
+      "category": "CONFLICT",
+      "description": "Version or concurrency conflict",
+      "retryable": true,
+      "httpStatus": 409,
+      "grpcStatus": "ABORTED",
+      "cliExit": 7,
+      "agentAction": "refresh_context",
+      "typeUri": "https://lafs.dev/errors/v1/conflict-version",
+      "docUrl": "https://lafs.dev/docs/errors/conflict-version"
+    },
+    {
+      "code": "E_RATE_LIMITED",
+      "category": "RATE_LIMIT",
+      "description": "Rate limit exceeded",
+      "retryable": true,
+      "httpStatus": 429,
+      "grpcStatus": "RESOURCE_EXHAUSTED",
+      "cliExit": 8,
+      "agentAction": "wait",
+      "typeUri": "https://lafs.dev/errors/v1/rate-limited",
+      "docUrl": "https://lafs.dev/docs/errors/rate-limited"
+    },
+    {
+      "code": "E_TRANSIENT_UPSTREAM",
+      "category": "TRANSIENT",
+      "description": "Upstream dependency temporary failure",
+      "retryable": true,
+      "httpStatus": 503,
+      "grpcStatus": "UNAVAILABLE",
+      "cliExit": 9,
+      "agentAction": "retry",
+      "typeUri": "https://lafs.dev/errors/v1/transient-upstream",
+      "docUrl": "https://lafs.dev/docs/errors/transient-upstream"
+    },
+    {
+      "code": "E_INTERNAL_UNEXPECTED",
+      "category": "INTERNAL",
+      "description": "Unexpected internal failure",
+      "retryable": false,
+      "httpStatus": 500,
+      "grpcStatus": "INTERNAL",
+      "cliExit": 1,
+      "agentAction": "escalate",
+      "typeUri": "https://lafs.dev/errors/v1/internal-unexpected",
+      "docUrl": "https://lafs.dev/docs/errors/internal-unexpected"
+    },
+    {
+      "code": "E_CONTEXT_MISSING",
+      "category": "CONTRACT",
+      "description": "Required context ledger fields are missing",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "FAILED_PRECONDITION",
+      "cliExit": 6,
+      "agentAction": "retry_modified",
+      "typeUri": "https://lafs.dev/errors/v1/context-missing",
+      "docUrl": "https://lafs.dev/docs/errors/context-missing"
+    },
+    {
+      "code": "E_CONTEXT_STALE",
+      "category": "CONFLICT",
+      "description": "Context ledger or references are stale",
+      "retryable": true,
+      "httpStatus": 409,
+      "grpcStatus": "ABORTED",
+      "cliExit": 7,
+      "agentAction": "refresh_context",
+      "typeUri": "https://lafs.dev/errors/v1/context-stale",
+      "docUrl": "https://lafs.dev/docs/errors/context-stale"
+    },
+    {
+      "code": "E_MIGRATION_UNSUPPORTED_VERSION",
+      "category": "MIGRATION",
+      "description": "Requested protocol/schema version unsupported",
+      "retryable": false,
+      "httpStatus": 426,
+      "grpcStatus": "FAILED_PRECONDITION",
+      "cliExit": 10,
+      "agentAction": "stop",
+      "typeUri": "https://lafs.dev/errors/v1/migration-unsupported-version",
+      "docUrl": "https://lafs.dev/docs/errors/migration-unsupported-version"
+    },
+    {
+      "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+      "category": "VALIDATION",
+      "description": "Unrecognized expansion field in _expand parameter",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2,
+      "agentAction": "retry_modified",
+      "typeUri": "https://lafs.dev/errors/v1/disclosure-unknown-field",
+      "docUrl": "https://lafs.dev/docs/errors/disclosure-unknown-field"
+    },
+    {
+      "code": "E_MVI_BUDGET_EXCEEDED",
+      "category": "VALIDATION",
+      "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+      "retryable": false,
+      "httpStatus": 413,
+      "grpcStatus": "RESOURCE_EXHAUSTED",
+      "cliExit": 2,
+      "agentAction": "retry_modified",
+      "typeUri": "https://lafs.dev/errors/v1/mvi-budget-exceeded",
+      "docUrl": "https://lafs.dev/docs/errors/mvi-budget-exceeded"
+    },
+    {
+      "code": "E_FIELD_CONFLICT",
+      "category": "CONTRACT",
+      "description": "Mutually exclusive field selection modes (single-field extraction and multi-field filtering cannot be combined)",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2,
+      "agentAction": "stop",
+      "typeUri": "https://lafs.dev/errors/v1/field-conflict",
+      "docUrl": "https://lafs.dev/docs/errors/field-conflict"
+    }
+  ]
+}