Lower-priority/rare Modal constructs: Dict/Queue, @modal.batched, NetworkFileSystem, CloudBucketMount, Cron/Period objects

[scttfrdmn]

Context

Part of a systematic Modal-compatibility pass (see
`docs/modal-compatibility-matrix.md`). Grouping the rare/low-priority
constructs found in the survey into one tracking issue rather than filing
a dozen near-empty issues — split any of these out individually once/if
real usage is observed.

Constructs (all confirmed NOT_PRESENT_AT_ALL in calque today)

• `modal.Dict`/`modal.Queue` — distributed KV store / FIFO-per-
  partition queue. Rare in the wild (5-6/212 files in modal-examples).
• `@modal.batched(max_batch_size=, wait_ms=)` — dynamic input batching.
  Very rare (2/212 files; not found at all in the independent-repo sample).
• `modal.NetworkFileSystem` — deprecated upstream too (Modal steers
  users to Volume); if any real script still uses it, calque's Volume→S3-
  prefix mapping is the WRONG model (NFS is live-shared/EFS-shaped, not
  snapshot-and-sync like Volume).
• `modal.CloudBucketMount` — direct S3/R2/GCS mount via
  `mountpoint-s3`; a different (and more restrictive) primitive than
  Volume — no append writes, no seek+write, must open in truncate mode.
• `modal.Cron(cron_string, timezone=)` / `modal.Period(days=, hours=, ...)`
  as OBJECT forms — calque only recognizes the bare `schedule=` string
  kwarg case today; a `modal.Cron(...)`/`modal.Period(...)` call
  expression likely falls into the generic "unmodeled decorator arg"
  fallback rather than the dedicated `schedule=` leak. Worth noting: when
  present, scheduling is OFTEN the entire app (e.g. earth-mover/forecast-
  datacube-demo uses only plain functions + Cron + `.remote()`) — not as
  rare a SHAPE as the raw file-count suggests, even though the specific
  object-form recognition gap is narrow.
• `cloud=` kwarg — picks AWS/GCP/OCI/auto; directly relevant to
  calque's own translation story (a script already saying `cloud="aws"`
  is telling you something calque should probably read) but not yet
  recognized at all (`region=` IS recognized+leaked; `cloud=` is not).
• `App.include`/`.deploy`/`.run` lifecycle nuances (ephemeral vs.
  deployed, rolling vs. recreate deploy strategy) — calque has no
  "deployed app" concept at all; likely a legitimate long-term scope
  question rather than a near-term gap to close.

Ask

No action requested yet — tracking so these don't need to be rediscovered
from scratch by a future adopter's script. Revisit priority if real usage
surfaces (e.g. a future adopter's script uses `modal.Cron` directly, or
`cloud=` shows up and matters for routing).

[scttfrdmn]

Progress: cloud= done (2026-08-07, commit ce4c0ac)

Pulled cloud= out as a cheap, low-risk win (mirrors the already-working
region= pattern exactly — ir.Config.Cloud + a dedicated "recorded but NOT
honored (calque always targets AWS)" leak). Verified with a live repro,
covered in testdata/scripts/portable_config.py + TestParsePortableConfig.

Remaining, untouched per this issue's original "no action yet" scope:
modal.Dict/Queue, @modal.batched, modal.NetworkFileSystem,
modal.CloudBucketMount, modal.Cron/Period object forms,
App.include/.deploy/.run lifecycle nuances. Each is its own real piece of
work with no evidence of real-world need yet — leaving this issue open to
keep tracking them as a bundle, per its original intent.

[scttfrdmn]

cloud= is done — confirmed in docs/modal-compatibility-matrix.md (fixed 2026-08-07, commit ce4c0ac). Narrowing this issue's remaining scope to the other five constructs: Dict/Queue, @modal.batched, NetworkFileSystem, CloudBucketMount, Cron/Period objects — all still confirmed untouched (⬜ in the compat matrix).

[scttfrdmn]

Partially addressed in a20f4f9 — the one construct from this grab-bag with a real usage signal.

modal.Cron(cron_string, timezone=)/modal.Period(days=, hours=, ...) object forms are now recognized structurally (pyast's _schedule_marker, mirroring _volumes_map's existing precedent for descending into a call-expression kwarg value) rather than falling through to the generic __unparsed__ stringify path, which previously landed garbage JSON text in ir.Config.Schedule while the leak misleadingly implied a clean string had been recorded.

Cron's cron string is extracted verbatim (timezone= discarded, matching the bare-string form's existing posture). Period's days=/hours=/minutes=/seconds= kwargs are additive (Modal combines any subset) and are summed into a normalized "<n>d<n>h<n>m<n>s" string. Still recorded-not-honored — no scheduler exists in the spike; the leak now notes when it recognized an object form specifically.

New fixture testdata/scripts/schedule_object.py (Cron, Period, and a bare-string regression guard); test TestParseScheduleObjectForms (internal/parse/parse_test.go).

The other 6 constructs this issue tracks (modal.Dict/Queue, @modal.batched, NetworkFileSystem, CloudBucketMount, cloud= — already done separately, and App.include/.deploy/.run) remain untouched — zero usage signal for any of them per the earlier triage pass, correctly left alone. Leaving this issue open for those; re-title or split if any of them gets a real signal later.

Full repo go build/go vet/gofmt -l/go test ./... clean.

[scttfrdmn]

Detection-signal fix in 2bc0474 — prep for the upcoming real-world corpus pressure-test (calque#79), per this session's own recommendation.

modal.Dict.from_name/Queue.from_name/NetworkFileSystem.from_name previously vanished entirely (no visit_Assign branch matched them). modal.CloudBucketMount(...) used inline as a volumes= value was silently miscategorized as an ordinary Volume mount — no leak, no distinguishing tag, _volumes_map's non-Name fallback just unparsed it. App.include/.deploy call sites also fell through untouched.

None of these are modeled by this change — it only makes each distinguishable: a named where tag (modal.Dict, modal.Queue, modal.NetworkFileSystem, modal.CloudBucketMount, App.include) in the leak report, so a real script hitting one is a clean grep hit instead of silence or a false Volume classification. Deliberately did NOT tag bare .run() — too generic a method name across unrelated objects to tag reliably.

Escalation trigger per the earlier planning pass: if 2+ independent real scripts in the growing corpus hit the same construct, split it into its own issue with the real script as a fixture. Still zero real-usage evidence for any of the 6 remaining constructs — this just ensures the corpus workflow will actually SEE it if that changes.

New fixture testdata/scripts/rare_constructs.py; test TestParseRareConstructsAreTaggedNotSilent (internal/parse/parse_test.go). Full repo go build/go vet/gofmt -l/go test ./... clean.

[scttfrdmn]

Closed part of this backlog via #182 (merged 32b978a7): @modal.batched(...) now gets the same distinguishable leak-tagging treatment its four siblings already had (modal.Dict/Queue/NetworkFileSystem.from_name(...), modal.CloudBucketMount(...)).

Before this fix, @modal.batched had zero recognition in tools/pyast/pyast.py — it fell through completely unnoticed, no leak at all, unlike the other four rare constructs. _describe_fn now matches it by trailing decorator name and appends a "modal.batched" entry to helper_leaks, picked up automatically by internal/parse/parse.go's existing generic HelperLeaks -> KindUnhandledCase channel (no Go-side changes needed). Covered by a new fixture (testdata/scripts/batched_function.py) and test (TestParseModalBatchedDecoratorLeaks), and docs/modal-compatibility-matrix.md's @modal.batched/@app.batched rows are updated from ⬜ to 🟨.

To be explicit about scope: this is leak-tagging only, matching the "fake behind the seam, leak the gap" posture for rare constructs. Real execution modeling of @modal.batched's request-coalescing behavior — and likewise Dict/Queue/NetworkFileSystem/CloudBucketMount's real execution semantics (not just their existing leak tags) — remains intentionally out of scope and unaddressed by this change.

Not closing this issue — leaving it open in case other items in the backlog remain, or for your review.

[scttfrdmn]

Workstream A (modal.CloudBucketMount -> real S3 mount) is done: merged via #185 (commit 1ea7064).

modal.CloudBucketMount(bucket_name, key_prefix=, read_only=), used INLINE as a volumes= value (the real Modal idiom — constructed directly in the dict, never assigned to a variable first), now resolves to a real mountpoint-s3 mount against the script's own S3 bucket — it is no longer leak-only.

Summary of the mapping:

• tools/pyast/pyast.py (_volumes_map/_cloud_bucket_mount): extracts bucket_name (positional or kwarg), key_prefix, read_only into a {"__cloud_bucket_mount__": {...}} wire shape, distinguishable from an ordinary Volume mount. Falls back to the pre-existing "recognized but not modeled" leak only when bucket_name isn't a string literal. secret= and bucket_endpoint_url=/requester_pays=/force_path_style= are each leaked separately, informationally, as unhonored (instance's own IAM role is used instead; AWS S3 default settings only).
• internal/ir/ir.go: new ir.CloudBucketMount type; Function/Class gained CloudBucketMounts map[string]CloudBucketMount.
• internal/parse/parse.go: readConfigKwargs widened to decode both the plain-Volume and CloudBucketMount shapes out of one volumes= dict.
• internal/plan/cloudbucketmount.go (new): ResolveCloudBucketMounts (dedupe-by-mount-path, conflict-leak) + MountCommands (idempotent mount-s3 install, mkdir -p, mount-s3 <bucket> <mountpoint> [--prefix] [--read-only]).
• internal/exec/bootstrap.go: new BootstrapConfig.CloudBucketMountLines, spliced in before @enter runs (both HostMode and docker-mode paths).
• internal/plan/iam.go: RealRunPolicy gained an extraBuckets []string param, granting read/write/list on the script's own bucket(s) — separate from calque's --bucket staging area.
• cmd/calque/realrun.go / cmd/calque/fleetrun.go: wired into both the single-instance and fleet (dedicated-fallback-instance) paths.
• docs/modal-compatibility-matrix.md: modal.CloudBucketMount row updated from ⬜ to ✅.
• New fixture testdata/scripts/cloud_bucket_mount.py + tests across internal/parse, internal/plan, internal/exec.

Still leak-only / explicitly out of scope for this PR: modal.Dict, modal.Queue, modal.NetworkFileSystem, App.include/.deploy/.run. modal.NetworkFileSystem is a separate, larger workstream planned for later — not attempted here.

Leaving #91 open for that deferred NetworkFileSystem workstream.