;; ==========================================================================
;; boundary.sx — SX language boundary contract
;;
;; Declares the core I/O primitives that any SX host must provide.
;; This is the LANGUAGE contract — not deployment-specific.
;;
;; Pure primitives (Tier 1) are declared in primitives.sx.
;; Deployment-specific I/O lives in boundary-app.sx.
;; Per-service page helpers live in {service}/sx/boundary.sx.
;;
;; Format:
;;   (define-io-primitive "name"
;;     :params (param1 param2 &key ...)
;;     :returns "type"
;;     :async true
;;     :doc "description"
;;     :context :request)
;;
;; ==========================================================================


;; --------------------------------------------------------------------------
;; Tier 1: Pure primitives — declared in primitives.sx
;; --------------------------------------------------------------------------

(declare-tier :pure :source "primitives.sx")


;; --------------------------------------------------------------------------
;; Tier 2: Core I/O primitives — async, side-effectful, need host context
;;
;; These are generic web-platform I/O that any SX web host would provide,
;; regardless of deployment architecture.
;; --------------------------------------------------------------------------

;; Request context

(define-io-primitive "current-user"
  :params ()
  :returns "dict?"
  :async true
  :doc "Current authenticated user dict, or nil."
  :context :request)

(define-io-primitive "request-arg"
  :params (name &rest default)
  :returns "any"
  :async true
  :doc "Read a query string argument from the current request."
  :context :request)

(define-io-primitive "request-path"
  :params ()
  :returns "string"
  :async true
  :doc "Current request path."
  :context :request)

(define-io-primitive "request-view-args"
  :params (key)
  :returns "any"
  :async true
  :doc "Read a URL view argument from the current request."
  :context :request)

(define-io-primitive "csrf-token"
  :params ()
  :returns "string"
  :async true
  :doc "Current CSRF token string."
  :context :request)

(define-io-primitive "abort"
  :params (status &rest message)
  :returns "nil"
  :async true
  :doc "Raise HTTP error from SX."
  :context :request)

;; Routing

(define-io-primitive "url-for"
  :params (endpoint &key)
  :returns "string"
  :async true
  :doc "Generate URL for a named endpoint."
  :context :request)

(define-io-primitive "route-prefix"
  :params ()
  :returns "string"
  :async true
  :doc "Service URL prefix for dev/prod routing."
  :context :request)

;; Config and host context (sync — no await needed)

(define-io-primitive "app-url"
  :params (service &rest path)
  :returns "string"
  :async false
  :doc "Full URL for a service: (app-url \"blog\" \"/my-post/\")."
  :context :config)

(define-io-primitive "asset-url"
  :params (&rest path)
  :returns "string"
  :async false
  :doc "Versioned static asset URL."
  :context :config)

(define-io-primitive "config"
  :params (key)
  :returns "any"
  :async false
  :doc "Read a value from host configuration."
  :context :config)


;; --------------------------------------------------------------------------
;; Boundary types — what's allowed to cross the host-SX boundary
;; --------------------------------------------------------------------------

(define-boundary-types
  (list "number" "string" "boolean" "nil" "keyword"
        "list" "dict" "sx-source"))