joewiz

eXist-db 6.4.0: why a scheduled XQuery job's parameters arrive empty

[This text was prompted by Joe, drafted by Claude Code, and reviewed by Joe.]

Written in response to a question in the eXist-db Slack about a background job that reports successful scheduling but never advances past its queued state. The root cause turned out to be an eXist bug rather than an application error, and the diagnostic path is worth writing down because the failure is completely silent.

TL;DR

An external variable declared with a default value ignores the value supplied by the external environment:

joewiz

╭─── Claude Code v2.1.59 ───────────────────────────────────────────────────────────────╮
│                                               │ Tips for getting started              │
│               Welcome back Joe!               │ Run /init to create a CLAUDE.md file… │
│                                               │ ───────────────────────────────────── │
│                                               │ Recent activity                       │
│                   ▗ ▗   ▖ ▖                   │ No recent activity                    │
│                                               │                                       │
│                     ▘▘ ▝▝                     │                                       │
│   Sonnet 4.6 · Claude Pro · Joe Wicentowski   │                                       │

joewiz

╭─── Claude Code v2.1.50 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                             │ Tips for getting started                                                                                                    │
│      Welcome back Joe!      │ Run /init to create a CLAUDE.md file with instructions for Claude                                                           │
│                             │ ─────────────────────────────────────────────────────────────────                                                           │
│                             │ Recent activity                                                                                                             │
│                             │ No recent activity                                                                                                          │
│              ✻              │                                            

joewiz

╭─── Claude Code v2.1.50 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                             │ Tips for getting started                                                                                                    │
│      Welcome back Joe!      │ Run /init to create a CLAUDE.md file with instructions for Claude                                                           │
│                             │ ─────────────────────────────────────────────────────────────────                                                           │
│                             │ Recent activity                                                                                                             │
│                             │ No recent activity                                                                                                          │
│              ✻              │                                             

joewiz

❯ I plan to repeat this on some other repositories. Do you have any lessons you'd like me to pass on to Claude for the next session, to help proceed more directly toward the solution we adopted?

Key technical facts (things that would have saved the most time if known upfront):

1. HTTPS on port 8443, not HTTP on 8080 — @existdb/gulp-exist v5 defaults to secure: true; node-exist's compat shim converts that to protocol, overriding any HTTP setting from env vars. Don't fight it — use HTTPS and map port 8443 in CI, matching roaster's approach. Set rejectUnauthorized: false in the test runner for the self-signed cert.
2. expath-pkg.xml path — Use semver.xqm, not content/semver.xqm. eXist-db's EXPath resolver prepends content/ automatically; doubling it breaks eXist-db 5.0.0 (6.x is forgiving). eXist-db-specific metadata (<author>, <website>, <status>, etc.) belongs only in repo.xml, not expath-pkg.xml.
3. XQSuite test runner — Use inspect:module-functions(xs:anyURI("xm

joewiz

❯ Take a look around this repository and let me know if you have any suggestions for bug fixes or improvements. 

⏺ Explore(Explore repository structure)
  ⎿  Done (15 tool uses · 56.7k tokens · 45s)
  (ctrl+o to expand)

⏺ Let me verify the most notable finding - the potential bug in semver:eq().

⏺ Read 1 file (ctrl+o to expand)

joewiz

xquery version "3.1";

(: This uses the eXist cache module to mimic xsl:accumulator approach described 
 : by Norm Walsh at https://so.nwalsh.com/2023/08/08-accumulators :)

declare function local:initiate-cache() {
    cache:destroy("quotes"), 
    cache:create("quotes", map{}), 
    cache:put("quotes", "counter", 1)
};

joewiz

xquery version "3.1";

(: Convert a sequence of XQuery maps into CSV or TSV.
 : Each map becomes one row.
 : The entries' keys become column headers.
 :)

declare variable $local:default-options := 
    map {
        (: Character to separate cells with :)

joewiz

xquery version "3.1";

(: @see https://github.com/eXist-db/exist/commit/53bdb54c664a8063e43392e0b0fb9eac57baf67d#diff-fc5225a3545e6b6807e7810bc9e40219500842a68dbb49a7eb83670016b160ab :)

declare boundary-space preserve;

let $json-ignore-whitespace-text-nodes-param-xml := 
    <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
        <output:method value="json"/>
        <exist:json-ignore-whitespace-text-nodes value="yes"/>

joewiz

xquery version "3.1";

import module namespace versions="http://exist-db.org/apps/public-repo/versions" at "/db/apps/public-repo/modules/versions.xqm";

let $exist-versions := ("4.11.0", "5.5.1", "6.1.0")
let $abbrevs := ("shared-resources", "dashboard", "doc", "eXide", "functx", "fundocs", "markdown", "monex", "usermanager")
let $header-row := ("package", $exist-versions ! ("eXist " || .)) => string-join(", ")
let $body-rows :=
    for $abbrev in $abbrevs
    let $packages := doc("/db/apps/public-repo-data/metadata/package-groups.xml")//package-group[abbrev = $abbrev]//package