agentskeptic 0.1.1

package/schemas/openapi-commercial-v1.yaml

@@ -0,0 +1,215 @@
+openapi: "3.0.3"
+info:
+  title: AgentSkeptic commercial license API
+  version: "1.0.0"
+  contact:
+    url: https://agentskeptic.com
+  x-agentskeptic-distribution:
+    repository: https://github.com/jwekavanagh/agentskeptic
+    npmPackage: https://www.npmjs.com/package/agentskeptic
+    openApi: https://agentskeptic.com/openapi-commercial-v1.yaml
+  description: "State verification engine: read-only SQL checks that database state matches expectations from structured tool activity (not arbitrary logs)—not proof of execution\n\nMachine-readable contract for license preflight used by the published npm CLI.\nBase URL is your deployed app origin (same as NEXT_PUBLIC_APP_URL).\n"
+externalDocs:
+  description: "First-run integration guide"
+  url: https://agentskeptic.com/integrate
+servers:
+  - url: https://agentskeptic.com
+    description: Replace with your deployment origin
+paths:
+  /api/v1/usage/reserve:
+    post:
+      operationId: reserveUsage
+      summary: Reserve one verification or enforcement run (license preflight)
+      description: >
+        Called by the commercial CLI before contract verify, quick verify, or enforce.
+        Requires Bearer API key. Body run_id must be idempotent per key.
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReserveRequest"
+      responses:
+        "200":
+          description: Allowed; quota consumed or duplicate run_id returned without double-charge
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReserveAllowed"
+        "400":
+          description: Bad request (missing/invalid body, skewed issued_at)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReserveError"
+        "401":
+          description: Invalid or revoked API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReserveError"
+        "403":
+          description: Quota exceeded or entitlement denied
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReserveError"
+        "503":
+          description: Server error during reservation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReserveError"
+  /api/v1/commercial/plans:
+    get:
+      operationId: getCommercialPlans
+      summary: Public commercial plan catalog (no secrets)
+      responses:
+        "200":
+          description: Plan metadata for display and integration
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CommercialPlansResponse"
+  /api/public/verification-reports:
+    post:
+      operationId: createPublicVerificationReport
+      summary: Persist a shareable verification report (public ingestion; size-limited; optional env disable)
+      tags:
+        - PublicVerificationReports
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PublicVerificationReportCreate"
+      responses:
+        "201":
+          description: Report stored; URL is canonical origin + /r/{id}
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PublicVerificationReportCreated"
+        "400":
+          description: Invalid JSON or failed schema validation
+        "413":
+          description: Request body exceeds maximum allowed size
+        "503":
+          description: Public report ingestion disabled or server unavailable
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API key
+  schemas:
+    PublicVerificationReportCreate:
+      description: >
+        Discriminated envelope (schemaVersion 1). Workflow branch includes WorkflowResult + truth report text.
+        Quick branch includes QuickVerifyReport + human report text + workflowDisplayId for labeling.
+      type: object
+      additionalProperties: true
+    PublicVerificationReportCreated:
+      type: object
+      additionalProperties: false
+      required:
+        - schemaVersion
+        - id
+        - url
+      properties:
+        schemaVersion:
+          type: integer
+          const: 1
+        id:
+          type: string
+          format: uuid
+        url:
+          type: string
+          format: uri
+          description: GET this URL to render the stored report (HTML)
+    ReserveRequest:
+      type: object
+      required:
+        - run_id
+        - issued_at
+      properties:
+        run_id:
+          type: string
+          maxLength: 256
+        issued_at:
+          type: string
+          format: date-time
+          description: ISO8601; server rejects if skew from now exceeds 300 seconds
+        intent:
+          type: string
+          enum: [verify, enforce]
+          default: verify
+          description: enforce requires paid plan with active subscription; verify requires active subscription on individual/team/business/enterprise
+    ReserveAllowed:
+      type: object
+      required:
+        - allowed
+        - plan
+        - limit
+        - used
+      properties:
+        allowed:
+          type: boolean
+          enum: [true]
+        plan:
+          type: string
+          enum: [starter, individual, team, business, enterprise]
+        limit:
+          type: integer
+        used:
+          type: integer
+    ReserveError:
+      type: object
+      properties:
+        allowed:
+          type: boolean
+          enum: [false]
+        code:
+          type: string
+          description: >
+            Examples BAD_REQUEST, INVALID_KEY, QUOTA_EXCEEDED, VERIFICATION_REQUIRES_SUBSCRIPTION,
+            ENFORCEMENT_REQUIRES_PAID_PLAN, SUBSCRIPTION_INACTIVE, BILLING_PRICE_UNMAPPED, SERVER_ERROR
+        message:
+          type: string
+        upgrade_url:
+          type: string
+          format: uri
+          description: Present for some 403 entitlement responses
+    CommercialPlansResponse:
+      type: object
+      required:
+        - schemaVersion
+        - plans
+      properties:
+        schemaVersion:
+          type: integer
+        plans:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/PublicPlan"
+    PublicPlan:
+      type: object
+      properties:
+        includedMonthly:
+          oneOf:
+            - type: integer
+            - type: "null"
+        monthlyUsdCents:
+          oneOf:
+            - type: integer
+            - type: "null"
+        displayPrice:
+          type: string
+        marketingHeadline:
+          type: string
+        audience:
+          type: string
+        valueUnlock:
+          type: string

package/schemas/plan-validation-core.schema.json

@@ -0,0 +1,95 @@
+{
+  "$id": "https://agentskeptic.com/schemas/plan-validation-core.schema.json",
+  "title": "PlanValidationCore",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "rules"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "rules": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/planRule" }
+    }
+  },
+  "$defs": {
+    "rowKindEnum": {
+      "type": "string",
+      "enum": ["add", "modify", "delete", "rename", "copy", "type_change", "unmerged"]
+    },
+    "planRule": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "pattern", "rowKinds"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
+            "kind": { "const": "matchingRowsMustHaveRowKinds" },
+            "description": { "type": "string" },
+            "pattern": { "type": "string", "minLength": 1 },
+            "rowKinds": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/rowKindEnum" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "pattern"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
+            "kind": { "const": "forbidMatchingRows" },
+            "description": { "type": "string" },
+            "pattern": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "pattern", "rowKinds"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
+            "kind": { "const": "requireMatchingRow" },
+            "description": { "type": "string" },
+            "pattern": { "type": "string", "minLength": 1 },
+            "rowKinds": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/rowKindEnum" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "allowPatterns"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
+            "kind": { "const": "allChangedPathsMustMatchAllowlist" },
+            "description": { "type": "string" },
+            "allowPatterns": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "fromPattern", "toPattern", "includeCopy"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
+            "kind": { "const": "requireRenameFromTo" },
+            "description": { "type": "string" },
+            "fromPattern": { "type": "string", "minLength": 1 },
+            "toPattern": { "type": "string", "minLength": 1 },
+            "includeCopy": { "type": "boolean" }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/public-verification-report-v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$id": "https://agentskeptic.com/schemas/public-verification-report-v1.schema.json",
+  "title": "PublicVerificationReportEnvelopeV1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "kind", "workflowResult", "truthReportText"],
+      "properties": {
+        "schemaVersion": { "type": "integer", "const": 1 },
+        "kind": { "type": "string", "const": "workflow" },
+        "workflowResult": {
+          "$ref": "https://agentskeptic.com/schemas/workflow-result.schema.json"
+        },
+        "truthReportText": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1048576
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "kind",
+        "workflowDisplayId",
+        "quickReport",
+        "humanReportText"
+      ],
+      "properties": {
+        "schemaVersion": { "type": "integer", "const": 1 },
+        "kind": { "type": "string", "const": "quick" },
+        "workflowDisplayId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "quickReport": {
+          "$ref": "https://agentskeptic.com/schemas/quick-verify-report.schema.json"
+        },
+        "humanReportText": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1048576
+        }
+      }
+    }
+  ]
+}

package/schemas/quick-verify-report.schema.json

@@ -0,0 +1,251 @@
+{
+  "$id": "https://agentskeptic.com/schemas/quick-verify-report.schema.json",
+  "title": "QuickVerifyReport",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "verdict",
+    "summary",
+    "verificationMode",
+    "scope",
+    "ingest",
+    "units",
+    "exportableRegistry",
+    "productTruth"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 4 },
+    "verdict": { "type": "string", "enum": ["pass", "fail", "uncertain"] },
+    "summary": { "type": "string", "minLength": 1 },
+    "verificationMode": { "type": "string", "const": "inferred" },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "quickVerifyVersion",
+        "capabilities",
+        "limitations",
+        "ingestContract",
+        "groundTruth"
+      ],
+      "properties": {
+        "quickVerifyVersion": { "type": "string", "const": "1.1.0" },
+        "capabilities": {
+          "type": "array",
+          "const": ["inferred_row", "inferred_related_exists"]
+        },
+        "limitations": {
+          "type": "array",
+          "const": [
+            "quick_verify_inferred_row_and_related_exists_only",
+            "no_multi_effect_contract",
+            "no_destructive_or_forbidden_row_contract",
+            "contract_replay_export_row_tools_only"
+          ]
+        },
+        "ingestContract": { "type": "string", "const": "structured_tool_activity" },
+        "groundTruth": { "type": "string", "const": "read_only_sql" }
+      }
+    },
+    "ingest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reasonCodes", "malformedLineCount"],
+      "properties": {
+        "reasonCodes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "malformedLineCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ingestWarnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code"],
+        "properties": {
+          "code": { "type": "string" },
+          "actionKey": { "type": "string" }
+        }
+      }
+    },
+    "runHeaderReasonCodes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "units": {
+      "type": "array",
+      "items": {
+        "allOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "unitId",
+              "kind",
+              "verdict",
+              "confidence",
+              "reasonCodes",
+              "sourceAction",
+              "contractEligible",
+              "inference",
+              "verification",
+              "explanation",
+              "reconciliation"
+            ],
+            "properties": {
+              "unitId": { "type": "string", "minLength": 1 },
+              "kind": { "type": "string", "enum": ["row", "related_exists"] },
+              "verdict": {
+                "type": "string",
+                "enum": ["verified", "fail", "uncertain"]
+              },
+              "confidence": { "type": "number" },
+              "reasonCodes": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "sourceAction": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["toolName", "actionIndex"],
+                "properties": {
+                  "toolName": { "type": "string" },
+                  "actionIndex": { "type": "integer", "minimum": 0 }
+                }
+              },
+              "contractEligible": { "type": "boolean" },
+              "inference": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["table", "rationale"],
+                "properties": {
+                  "table": { "type": "string" },
+                  "rationale": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  },
+                  "alternates": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": true
+                    }
+                  }
+                }
+              },
+              "verification": {
+                "type": "object",
+                "additionalProperties": true
+              },
+              "explanation": { "type": "string", "minLength": 1 },
+              "reconciliation": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["declared", "expected", "observed_database", "verification_verdict"],
+                "properties": {
+                  "declared": { "type": "string" },
+                  "expected": { "type": "string" },
+                  "observed_database": { "type": "string" },
+                  "verification_verdict": { "type": "string" }
+                }
+              },
+              "correctnessDefinition": {
+                "$ref": "https://agentskeptic.com/schemas/workflow-truth-report.schema.json#/$defs/correctnessDefinitionV1"
+              }
+            }
+          },
+          {
+            "if": {
+              "type": "object",
+              "required": ["verdict"],
+              "properties": { "verdict": { "const": "verified" } }
+            },
+            "then": {
+              "type": "object",
+              "properties": { "correctnessDefinition": false }
+            }
+          },
+          {
+            "if": {
+              "type": "object",
+              "required": ["verdict"],
+              "properties": { "verdict": { "enum": ["fail", "uncertain"] } }
+            },
+            "then": {
+              "type": "object",
+              "required": ["correctnessDefinition"]
+            }
+          }
+        ]
+      }
+    },
+    "exportableRegistry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tools"],
+      "properties": {
+        "tools": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "productTruth": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "doesNotProve",
+        "layers",
+        "quickVerifyProvisional",
+        "contractReplayPartialCoverage"
+      ],
+      "properties": {
+        "doesNotProve": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "type": "string",
+              "const": "Does not prove the tool or action actually executed."
+            },
+            {
+              "type": "string",
+              "const": "Does not prove a write or other state change occurred."
+            },
+            {
+              "type": "string",
+              "const": "Only proves that current database state matches expectations derived from structured tool activity (quick: inferred expectations)."
+            }
+          ],
+          "minItems": 3,
+          "maxItems": 3,
+          "items": false
+        },
+        "layers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["declared", "expected", "observed"],
+          "properties": {
+            "declared": {
+              "type": "string",
+              "const": "Declared: tool identity and parameters extracted from ingest (structured tool activity)."
+            },
+            "expected": {
+              "type": "string",
+              "const": "Expected: in quick mode, row and FK checks inferred from declared parameters (provisional, not a signed contract). In contract mode, registry-defined expectations from events."
+            },
+            "observed": {
+              "type": "string",
+              "const": "Observed: read-only SQL results at verification time."
+            }
+          }
+        },
+        "quickVerifyProvisional": { "type": "boolean", "const": true },
+        "contractReplayPartialCoverage": { "type": "boolean", "const": true }
+      }
+    }
+  }
+}