Production-readiness review
Reviewed October 2, 2026. Scope: runtime and prototypes, dependencies, tests, configuration, CLI, deployment files, documentation, and static marketing pages.
Decision: hardened core is locally validated; production certification is pending. No finite review can establish that software is issue-free. Release requires real ArcGIS/native-platform/cloud and operational evidence. The supported runtime is intentionally limited to qualified core behavior; original advanced modules remain research prototypes.
Assessment
| Dimension | Before review | Current assessment |
|---|---|---|
| Correctness | Release-blocking dependency/API/startup failures; unreliable IDs and geometry handling | Core repaired and covered by native/provider regression tests; real CDF certification required |
| Security | SQL interpolation, built-in demo accounts, ignored feature/auth claims, nonblocking scans | Bound core queries, strict inputs, required standalone auth, secret-safe HTTP errors, isolated prototypes; platform controls required |
| Performance | Unbounded reads, ambiguous TTL, timer/resource leaks, unused pool claims | Bounded full-fetch/results/cache/queue, serial connection ownership, native interruption and cleanup; workload qualification required |
| Maintainability | Divergent docs/config schemas and tests for missing APIs | Canonical docs and migration notes, lockfile, current tooling, runnable tests, explicit prototype boundary |
Useful foundations preserved: modular source organization, GeoJSON output intent, configurable sources, and deployment manifests. The review converted those into a smaller implementation with verifiable behavior.
Findings and dispositions
| Priority | Finding | Resolution / location |
|---|---|---|
| P0 | Both original runtime packages were unavailable from the public npm registry; connection APIs did not match DuckDB | Official pinned @duckdb/node-api, native lifecycle adapter in database.js (GitLab sign-in), reproducible lockfile |
| P0 | Container ran a model export and exited; advertised server/routes did not exist | Real authenticated diagnostic server (GitLab sign-in); corrected Docker entry point and health checks |
| P0 | Configuration/source/spatial SQL interpolation and ineffective sanitization | Bound paths/geometry/pagination and restricted identifiers in model (GitLab sign-in) and configuration (GitLab sign-in) |
| P0 | Default administrator credentials and unintegrated authorization claims | Removed built-in prototype accounts; required token for production/non-loopback server; prototypes excluded from distribution |
| P1 | Feature IDs were array positions; null/projected/mixed geometry and metadata handling were unsafe | Stable source IDs, identifier/family validation, WGS84 constraints, CDF metadata, full-fetch overflow rejection |
| P1 | Concurrent initialization and failed startup could leak/reuse resources | Shared initialization, cleanup/retry, serial bounded admission, native cancellation, idempotent draining close |
| P1 | Reads/cache lacked practical memory bounds; TTL units conflicted; cleanup timer remained active | Record/byte limits, documented milliseconds, bounded LRU cache/copy isolation, cleared unreferenced timer |
| P1 | Existing integration assertions invoked APIs absent from their modules | Replaced with real CSV/GeoParquet/GeoJSON/HTTP/CLI tests and lifecycle fault injection |
| P1 | Helm referenced absent helpers/ConfigMap/PVC/Service; Compose referenced absent monitoring files | Complete minimal internal chart; corrected non-root/read-only Compose/image; unrelated prototype services removed |
| P1 | CI scans tolerated findings and deployment jobs referenced missing values files | Blocking dependency/image checks, native image smoke/auth/shutdown checks, Helm validation; live deployment removed |
| P1 | Azure helper claimed deployment, provisioned incomplete infrastructure, and wrote credentials to disk | Helper now performs validation and prepares a source artifact only; versioned CDF workflow documented |
| P2 | Docs/landing pages claimed unimplemented endpoints, features, and production readiness | Canonical docs rewritten; historical docs/pages labeled; migration guidance and roadmap added |
Moving prototypes to src/experimental is a compatibility change for direct imports. Their remaining SQL, authentication/session, tenant, stream, plugin, graph, and adapter issues are unresolved inside the research boundary. These modules are not approved for production and are not enabled by supported configuration.
First-sprint local evidence (before P1)
npm.cmd run build passed: lint, 114 tests in six suites, enforced coverage thresholds, and configuration validation. Three optional CloudFS native tests are skipped in the normal build. Supported runtime coverage: 96.88% lines, 91.61% statements, 88.28% branches, and 92.19% functions. Experimental modules are excluded from that denominator. Coverage does not establish correctness of every possible source.
- Native spatial reads: checked-in CSV and generated GeoParquet/GeoJSON, including a quoted path.
- HTTP: authenticated source/metrics access, pagination/intersects, invalid inputs, readiness, sanitized native errors.
- Lifecycle: concurrent initialization/failure retry, queue expiry/saturation, initialization/total/execution deadlines, HTTP disconnect cancellation, actual native interruption/recovery, shutdown and cleanup. Streaming callback failures drain empty terminal chunks before reuse.
- Preflight: native CSV/GeoParquet schema/global ID/family/coordinate scans, drift fingerprints, incomplete/changed scans, metadata/byte/empty-source failures, sanitized reports and CLI exit codes.
- Capacity: 12 checked-in fixture scenarios passed with zero errors; oversized full-fetch rejection and real source update/TTL expiry checked. See recorded evidence and measurement limits.
- Runtime version: all 114 tests and lint also passed on Windows with an isolated, official checksum-verified Node 24.13.0 executable. System Node remains 22.14.0; Linux/ArcGIS certification is separate.
- Documentation/configuration: canonical links and supported environment examples.
- Dependency audit: zero reported vulnerabilities for the locked graph on the review date.
- Helm: lint and complete rendering checked with checksum-verified Helm 4.3.0. CI YAML was parsed locally; Linux jobs are configured for Node 22.14.0 and 24.13.0, read-only constrained image smoke/scan and archived evidence.
- Distribution: inspected package contents for absence of prototypes, research samples, and secrets.
The Windows host's PowerShell npm shim is misconfigured; npm.cmd and the installed npm CLI work. No system tool configuration was changed.
CloudFS integration review
The requested CloudFS read adapter is opt-in and uses credential environment references, temporary secrets, reviewed extension-version checks, safe errors, and one active CloudFS model per worker process. CSV/JSON records/GeoParquet and bound asterisk globs use the existing source/query contract. Docker installation is explicit; Helm supports existing provider Secret references.
Native evidence: the signed build 4ca1432 loaded with an isolated DuckDB 1.5.4 Node API. All three native agent-fixture tests passed: authenticated CSV/JSON/GeoParquet range reads, globs/spatial predicates/pagination, and temporary secrets. This was a dedicated compatibility test, not a dependency downgrade or production certification.
The unchanged app runtime is DuckDB 1.5.6. The three isolated 1.5.4 CloudFS fixture tests were rerun after deadline/serialization changes and passed. Its optional npm run test:cloudfs currently fails with CLOUDFS_UNAVAILABLE because no matching community build is published for the tested platform. Windows/Linux repository paths returned 404; DuckDB 1.5.4 builds are available. The reviewed extension also lacks SFTP host-key verification, process/account isolation, and secret redaction keys, and fails to route vfs+tls despite parsing it. SFTP and TLS-agent configuration for that revision are blocked. Real cloud accounts, TLS-agent fixes, token refresh/rotation, I/O cancellation, caching/resource limits, and lakehouse/write workflows remain release gates or roadmap work.
Helm was linted and rendered with provider Secret references; an attempted override of CDF_API_TOKEN was correctly rejected. Distribution includes the adapter, guide, and credential-free example, with no prototype/test-runtime dependencies.
Required external release gates
| Gate | Why local results are insufficient | Required evidence |
|---|---|---|
| ArcGIS 12.1 Linux CDF compatibility | Target is confirmed; no matching SDK/staging site is available here; repository is not a generated CDF scaffold | Follow the package/certification procedure; genuine .cdpk and registration/service/client/query/metadata/restart/overflow evidence |
| Linux/native image validation | Docker client exists but the engine/daemon is unavailable locally | Successful image build/scan and server/auth/read-only/shutdown smoke checks in CI or a qualified host |
| CloudFS activation | Pinned 1.5.6 community build unavailable; SFTP/TLS-routing limitations and no real cloud credentials | Signed matching reviewed build; native suite without override; provider permission/expiry/rotation/TLS/outage/load tests; upstream security fixes |
| Remote HTTPS/S3 behavior | Local tests use local files; production cloud credentials/endpoints are not available | Permission/outage/rotation/egress and real source schema/geometry/ID tests |
| Kubernetes rollout | Template validation does not run workloads or validate cluster policy/storage/identity | Staging rollout, Secret/workload identity/TLS/network policy/monitoring setup, rollback drill |
| Capacity and freshness | Local sample queries are not representative production load | Agreed limits and SLOs; load/soak test RSS/spill/latency/queue/freshness; recovery evidence |
The model trusts ArcGIS service permissions and does not apply per-user/tenant policies. Diagnostic tokens grant every configured source. Queue/initialization/execution/total deadlines bound caller waiting, while native cancellation remains cooperative. Timed-out work retains native ownership until it settles; supervisors must terminate/restart uncooperative workers. Source pagination assumes stable data and global unique IDs. DuckDB's memory budget does not bound all Node/native allocation. These limits are documented and reflected in the roadmap.
No production deployment or infrastructure provisioning was performed.
References: DuckDB Node Neo API, Esri provider contract, Esri deployment overview.
P1 implementation follow-up
The approved P1 build implements restricted pass-through queries, EPSG/ArcGIS geometry conversion, versioned schema contracts, source-aware caches, optional exclusive native workers and monitoring assets. See contracts and migration and delivered roadmap status. Full-fetch and one worker remain defaults.
Native regression coverage includes global IDs beyond page limits, parser injection/bounds, counts/IDs/extents/statistics, projections and rings, exact attribute values/dates, schema drift, source identities/races, cancellation/HEAD aborts, independent workers, scratch isolation and cleanup ownership. All 232 tests pass on Windows Node 22.14.0 and 24.13.0. Coverage on Node 22 is 97.76% lines, 94.70% statements, 92.56% branches and 95.15% functions; three optional incompatible-build CloudFS tests remain skipped in the normal suite. The three isolated DuckDB 1.5.4 CloudFS fixtures also pass after the P1 changes; the app runtime remains pinned at 1.5.6. All 12 capacity scenarios and the overflow/TTL-update checks pass. Fixture pooling, package boundaries, Helm/CI assets and dependency audit are verified separately in this build.
Jest was upgraded to 30.5.2 to remove the development dependency chain affected by GHSA-vfj7-8cjw-p6xm. npm installation/audit reports zero vulnerabilities. Pool comparisons use fresh processes with the same total native budget and archive engine/runtime/RSS/latency evidence. Live Prometheus/Grafana validation, Linux/container execution and ArcGIS staging certification remain open; these changes do not establish a production release.