Public Meridian standard · current

Wrangler Configuration Standard

This standard covers repository ownership of Cloudflare Worker configuration
in wrangler.jsonc. Cloudflare documents the supported fields and their
runtime/deployment semantics in its [Wrangler configuration
reference](https://developers.cloudflare.com/workers/wrangler/configuration/).
Meridian policy distinguishes authored intent, generated configuration and
live provider state.

Wrangler JSONC files may use this compact reference comment near the top:

// Public standard: https://agents.meridianstack.dev/standards/wrangler-configuration

Source ownership

Treat an authored Wrangler file as deployable configuration only when the
repository's deployment contract identifies it as such. Where Meridian Config
generates wrangler.jsonc, edit its canonical Config inputs, regenerate the
deterministic, non-secret file, **commit that generated projection alongside
its inputs**, and check for drift in CI. Treat it like a lockfile, not an
editable independent authority. Generated .wrangler/types/*.d.ts, local
Wrangler overrides and .dev.vars* remain untracked; do not hand-edit
generated files. A deliberately authored Wrangler file remains independently
source-owned. The generator and its configuration contract own precedence
and defaults.

Wrangler's configuration is the source of truth for the Worker configuration
that Wrangler reads. Meridian's provider and deployment configuration may own
additional repository intent such as target selection, generated-file paths,
build commands and reconciliation metadata. Those inputs are not interchangeable
with observed provider state. A successful local config check also does not
prove that a deployed Worker matches it.

Bindings and values

Use bindings for runtime services and resources, and vars for non-sensitive
configuration. Never place credentials or sensitive values in committed
configuration or plain-text vars. Declare required secret names when the
supported Wrangler version and deployment contract use that facility; supply
secret values through the approved local or provider secret boundary. Cloudflare
documents Worker secrets
and warns against storing sensitive information in vars.

Bindings, environments, migrations, asset directories, compatibility settings
and resource identifiers vary by Worker. Preserve intentional project-local
configuration instead of filling templates with placeholder resources. Use
explicit local overrides only when a runtime or environment needs a different
binding contract, and keep generated type declarations aligned with the
effective configuration.

Default Worker runtime posture

Classify each deployed Worker by actual workload before configuring it: authenticated
API/admin, public dynamic web, assets-first/static, scheduled/queue processor, or
provider/infrastructure service. A single named profile may be reused across
deployables with matching security and cost characteristics, but it does not
override route-specific caching or security requirements.

For active Workers with an executable runtime, prefer native Cloudflare Workers
Issues when supported by the repository-pinned Wrangler schema. Author
observability.issues.enabled: true inside the existing observability
configuration, preserving any configured invocation logs, persistent log and
trace destinations, and redaction controls. Do not add unsupported schema keys
to older Wrangler versions: upgrade and validate the pinned toolchain first.
For static-assets-only deployments, document whether Worker Issues provides
useful runtime evidence rather than assuming static requests execute a Worker.
The workspace currently pins Wrangler 4.149.0, which supports this setting.
[Wrangler 4.150.0 changes deploys to upload source maps by
default](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.150.0);
adopting that separate deployment behavior needs its own review rather than
being bundled into the Issues baseline.

Meridian's current source profiles are control-plane-api, queue-workflow,
assets-site, and client-workspaces-gateway. The profile names describe
workload; they do not assert the deployed access perimeter or replace
target-specific bindings, routes, authentication, or runtime settings. The
canonical provider config is authoritative for generated targets. The separate
Client Workspaces gateway keeps its authored Wrangler file.

WorkerWorkloadIssuesCompatibility dateSource posture
Agent OperationsAPI, Queue consumer and WorkflowEnabled2026-06-05queue-workflow; shared logs/traces defaults
Agent GatewayAPI gatewayEnabled2026-06-05control-plane-api; shared logs/traces defaults
Build RadarAPI, Queue consumer and scheduled handlerEnabled2026-06-05queue-workflow; shared logs/traces defaults
Database CatalogueControl-plane APIEnabled2026-06-05control-plane-api; shared logs/traces defaults
Managed Repository AssessmentControl-plane API and Workflow processingEnabled2026-06-05control-plane-api; shared logs/traces defaults
Software InventoryControl-plane APIEnabled2026-06-05control-plane-api; shared logs/traces defaults
Credential CatalogueControl-plane APIEnabled2026-06-05control-plane-api; shared logs/traces defaults
Configuration AssuranceControl-plane APIEnabled2026-06-05control-plane-api; shared logs/traces defaults
Meridian DocsWebsite Worker with static assetsEnabled2026-06-05assets-site; executable fallback handler
Agent StandardsStatic-assets-only siteDisabled2026-06-05assets-site; no authored Worker handler
App UI StorybookStatic-assets-only siteDisabled2026-08-16assets-site; no authored Worker handler
Client Workspaces GatewayAccess-assertion gateway with R2 bindingEnabled2026-09-07client-workspaces-gateway; authored config

For generated Worker targets, the shared provider defaults keep persisted logs
and invocation logs enabled at 100% sampling and persisted traces enabled at
25%, with the existing meridian-grafana-logs and meridian-grafana-traces
destinations. The two assets-only targets explicitly opt out of Issues because
they have no authored JavaScript handler whose failures the feature could
group. Meridian Docs has a Worker entrypoint and stays in the Issues profile.
Revisit these exceptions if either static-only target gains runtime code. These
source classifications do not establish whether a route is publicly reachable
or protected by Cloudflare Access; the live access perimeter is unknown.
The current 100% log and 25% trace sampling values are preserved from source;
event volumes, destination ingestion and resulting costs have not been measured.
Review those values against observed workload volume and current billing before
changing them.

The shared 2026-06-05 date, App UI's 2026-08-16 date, and Client Workspaces'
2026-09-07 date remain at the tested source values; this change does not
advance compatibility. Generated targets inherit nodejs_compat except
Meridian Docs, whose source explicitly clears the flag; this change preserves
both settings. A date or flag change requires target-package regression
evidence before it is accepted. No canonical target currently declares a CPU
limit, placement override, or enabled Workers runtime cache. Runtime cache remains off by
omission: do not add cache.enabled: true without endpoint-specific response
safety, cache-key/TTL/invalidation evidence, and a request-cost comparison.
Cloudflare charges the normal Workers request rate for cache hits and for
requests that otherwise would be free, including static assets and service
binding calls; a hit avoids Worker CPU execution but does not make the request
free. See Workers Cache pricing.

The repository declares hosted Workers Builds targets, but this source audit
does not establish the live trigger value of build_caching_enabled. That
provider state is unknown. Keep frozen-lockfile installation and narrow
watch paths as the source-side reproducibility baseline. Read the trigger with
an approved read-only provider path before deciding whether to enable or
disable its cache; do not infer it from a successful build or this Wrangler
configuration. The Client Workspaces gateway uses the existing Grafana
destination names from Meridian's canonical defaults, while their live
availability for that Worker remains unknown.

Use service-specific sampling levels. High-value queue/retry/ingress diagnostics
may need greater log and trace coverage than high-volume public content;
sampling should be changed on observed event volume and actual cost, not a
global percentage copied between repositories. Structured logs must exclude
authentication headers, secrets, raw private payloads and unbounded provider
responses. Cloudflare Issues, sampled logs and traces are diagnostics, not
authoritative D1/Queue/Workflow execution counts or proof of Grafana delivery.

Runtime cache versus build cache

Leave the Workers runtime cache disabled by default on authenticated,
tenant-specific, mutable or service-bound endpoints. Evaluate opt-in caching
only with proven public-response safety, explicit cache keys, TTL/invalidation
and comparison of request charges. Runtime Workers Cache can change the billable
request class for traffic including static assets and service bindings; it is
not a free generic performance switch. Do not confuse it with ordinary static
asset/CDN caching or application-level caching.

Cloudflare Workers Builds caching is configured on the hosted build trigger,
not through the Worker runtime wrangler.jsonc cache setting. Inspect the
provider's build_caching_enabled state with a reviewed, read-only provider
tool and preserve reproducible frozen package installs, build roots and
path-scoped watch paths. Repository build intent is not evidence of current
hosted trigger state. Provider caching may require a separately reviewed
reconciliation operation when drift is demonstrated.

Compatibility, limits and rollout

Keep tested compatibility_date values until the affected Worker packages
and APIs have been regression-tested with a specific proposed date. Keep
nodejs_compat where an older date or tested runtime needs it, and remove
redundant flags only after supported version and behaviour are verified.
Do not drive compatibility changes by the calendar alone.

Leave CPU limits and placement at documented provider defaults unless measured
CPU cost, request patterns, subrequest budget or workload behaviour justifies
a target-specific override. Long external I/O waits and CPU execution are
different cost/safety questions. If a Worker has elevated limits, retain them
until the controlling operation has credible bounded load and timeout evidence.

A successful configuration check proves authored/derived consistency, not
that the serving version or provider account matches it. Verify generated
Wrangler output against canonical Meridian Config, preserve bindings/routes/
secrets references and environment settings, inspect CI evidence, and keep
deployment creation, serving version, runtime health, Issues activation and
provider build-cache read-back as distinct outcomes. Record unknown provider
state as unknown, not disabled or healthy.

Validation and exceptions

Validate the config with the repository's pinned Wrangler tooling and its
repository-owned non-mutating drift check, when available. A check validates a
local declaration; it does not grant provider access or establish live state.
Keep account-specific values, Worker names, secrets and private deployment
details out of portable guidance. Document unusual configuration where its
purpose is not clear from the owning Config or application contract.

The repository pins Wrangler to a version that supports
observability.issues.enabled; its installed JSON schema is the local source of
truth for config validation. Repository policy checks cover the declared
Worker inventory, required Issues posture, the documented assets-only
exceptions, preserved logs/traces settings, compatibility dates and flags,
runtime-cache opt-ins, CPU limits, and placement overrides. A new exception
must be recorded here and in the source-level policy test before it is used.

Download raw Markdown · Standards index