Agents authoring extensions reliably miss the version upgrade discipline. The guidance exists in references/extension/references/model/upgrades.md but the loading path is too deep for agents to discover organically during extension development. Nothing in the observable feedback loop (quality score, push checks, type-check) surfaces the requirement.

The result: extensions get published with bumped version fields but no corresponding upgrades entry, leaving existing model instances stranded at their old typeVersion forever. Downstream, those instances silently skip future upgrade chains that assume the intermediate version was applied.

Current state

The upgrades doc clearly specifies the rules (last toVersion must equal version, chain must be chronologically ordered, no-op upgrades required even for non-schema-changing bumps).
The registry validates upgrade chain consistency at startup (runtime).
swamp extension push gates on adversarial review presence and quality score.
swamp extension quality evaluates 12 factors — none related to upgrade chain correctness.
Agents learn through the score/push feedback loop. If the loop doesn't surface the problem, agents don't learn about it.

Proposal

1. New quality rubric factor: `upgrade-chain-valid` (1 pt)

Conditions to earn:

If version equals the currentPublished version (or no published version exists): auto-pass (no upgrade needed for first publish or unchanged version).
If version differs from currentPublished: an upgrades array entry with toVersion == version must exist.
The upgrade chain must be chronologically ordered.
The last entry's toVersion must equal the model's version field.

This teaches agents through the normal workflow: run quality → see failure → read guidance → fix. The failure message should reference upgrades.md directly so agents can self-correct.

2. Push pre-flight warning (or block)

When swamp extension push detects a version bump without a corresponding upgrade entry:

Emit a warning: "Version bumped from {old} to {new} but no upgrades entry with toVersion={new} found. Existing instances will not auto-migrate. Add an upgrades entry (even a no-op) or pass --skip-upgrade-check to acknowledge."
Optionally block (exit 2) unless --skip-upgrade-check is passed, similar to how missing adversarial reviews prompt for confirmation.

3. Skill routing improvement

The extension guide's model-specific section references references/model/upgrades.md but only in a bullet list that agents rarely drill into. Consider:

Adding a brief inline callout in the extension guide's "Shared Development Workflow" section (step between "Version + manifest" and "Quality check"): "If bumping version from a published baseline, add an upgrades entry — see upgrades.md."
Having the quality factor's failure message include the exact file path to read.

Impact

Agents in the feedback loop learn the pattern after one failed quality check.
Extension authors (human or agent) get a guardrail before publishing broken upgrade chains.
Existing instances stop silently falling behind on typeVersion.

Context

Discovered while building a new extension (@webframp/aws/s3-inventory-observation) — first publish, so no upgrade was needed, but the question "did we handle version bumps correctly?" had no observable answer in the toolchain. An agent working on a subsequent version bump would have no signal that an upgrade entry is required until the registry throws at runtime on someone else's instance.

02Bog Flow

Open

8/13/2026, 7:40:01 PM

No activity in this phase yet.

03Sludge Pulse

Quality rubric + push gate for version upgrade chain correctness

Add an upstream-state method: status cannot answer whether commits are pushed

Docs: document auto-raise of open-file limit in swamp serve reference

swamp serve dies of descriptor exhaustion on an ordinary workload, having warned about it at startup

extension quality awards repository-verified 2/2 for a nonexistent or private GitHub repo

workflow resume truncates the run's log file, losing every earlier attempt's records

extension/guide.md quick reference uses -j, which no swamp command accepts

Catalog write-lock contention during extension load leaves a partial registry; auto-resolve fabricates 'local edits' and suggests a destructive --force re-pull

Add a list/discover method to the generated @swamp/aws types — no way to enumerate resources in a region

serve: stale empty directories in active-runs/ never cleaned up

Extension workflows: no way to override trigger configuration

swamp serve: webhook secrets should support @vault= resolution

WebSocket auth rate limiter blocks legitimate users when sharing IP with a failing client

Failing on claude validate

GC expired OAuth server tokens and control plane secrets

Client shows 'Authentication failed' when actually rate-limited

serve: cron ticks leak pending-run records, replaying every past tick on restart

Workers retry forever on permanent auth failures instead of backing off

Remote execution has no working network configuration: off-loopback serve requires TLS, but worker connect cannot connect over TLS

Support --grants-dir for loading grants from a directory

migrate-index still drops shallow-path entries on 2026.08.07.1 — #1584 marked shipped but no released version carries the fix (self-contained repro)

Server token definitions and encryption keys are not durable across pod restarts

data.latest() is memoized per run, contradicting the documented "sees current-run data" contract

Model lookup misreports EMFILE (too many open files) as a broken definition file and dumps a raw stacktrace

Lab Insights not publicly available

Docs: add swamp access group list-idp to access commands reference

serve telemetry identity warnings are diagnostic but not actionable — say how to fix them

swamp quest: drop the heartbeat field the server no longer sends

--grant-reload auto does not detect filesystem changes — blind to ConfigMap updates

Add native Bedrock Knowledge Base Retrieve support

migrate-index silently drops entries with shallow paths — all of workflows-evaluated/ and any root-level file

Cluster health snapshots with SSE streaming for swamp serve

Add swamp access group list-idp to enumerate IdP groups seen by the server

Grants directory loader skips symlinks — breaks Kubernetes ConfigMap mounts

Daemon telemetry flush: stop() can skip its final flush when a timer drain is already in flight

Docs: `swamp compile` subcommand doesn't exist

Guard the projector's full rewrites against the fail-open lease (ADV-6 from #1575/#1576)

Projector write amplification: board_totals/owner_devices full rewrites are owners × runs/day

Profile candidateIds prune costs a full ledger scan to build itself — 42.88M rows for one keyed read

Leaderboard phase 3: owner-grain board_totals so a cache miss is survivable at 10B

swamp serve is telemetry-dark: scheduled workflow runs never reach /ingest, and the daemon never flushes

CLI has never sent insert_id: retried telemetry batches are double-counted into cli_daily, inflating XP in an append-only ledger

Catalog backfill reconciles against the local cache, not the datastore

Extension bundle cache not invalidated when an imported sibling module changes (entry-file fingerprint only)

swamp serve: data.query fails permanently with "UNIQUE constraint failed: catalog.*" — one duplicate catalog 5-tuple aborts every catalog rebuild

dailyHistory range pushdown — deferred from #1576, and the measurement says why

score-rollup projector runs N× per cadence — the run gate is per-replica memory, not shared state

Docs: manual never mentions telemetry, and the serve/scheduling pages imply automated runs are visible when they are not

Explore: CLI binary update integrity lacks independent verification

Leaderboard phase 2: take score_grants off the board read path — read today from score_daily

Explore: reconcile quality rubric's dormant provenance factor

Explore: pull-time signature verification for extensions

Explore: transparency-log integration (Rekor) for extension signatures

Explore: publish-time artifact signing for extensions (cosign keyless)

Profile day drill-down returns 0 entries at the 5s ClickHouse ceiling for every operative

A ledger read failure still renders as 'no activity': loadProfileScore swallows to an empty standing behind HTTP 200

reconcile_from_disk_bench.ts fails deno check (stale DenoRuntime stub)

Improve multi-word search query handling and guidance

Retire the genesis_public flag and delete the dead cutover transcription scaffolding

Leaderboard phase 1: cache the board read and bust it on tier crossings (no schema change)

Catalog backfill deletes rows for any model whose data names are numeric

Docs: document catalog completeness check and --repair in doctor reference

Leaderboard board windows re-anchor on wall-clock while the rest of the view is frozen at asOf

Decision: move per-event grant MVs to day-grain — ledger is on track for ~1.5B score_grants / ~4B quest_grants

Leaderboard phase 5: score-rollup-projector write cost at 10B — ~430M rows scanned per 60s tick

Epic: /leaderboard and /u/{username} do not survive 10B events — measured audit + phased plan

Datastore-managed configuration for multi-instance serve deployments

Ghosts on the leaderboard 500

swamp command doesn't check cwd

swamp auth login process fails when run remotely

serve boot OOM: findAllGlobalSince loads all workflow runs as full aggregates during reconciliation

extension search: channel-filtered results carry null version fields, and multiple --channel values collapse instead of unioning

s3-datastore: localHasAllRemoteEntries uses bare rel instead of localRelPath, always returns false in namespaced mode

datastoreSetupExtension migrates .swamp/ to cache root instead of namespace directory

swamp serve writes outputs/ outside the bound namespace — silently never persisted to the remote datastore

s3-datastore: bulk pull writes to cache root instead of the namespace, wedging push and arming a full-datastore delete

git: add pull, fetch --tags, and cherry-pick methods

Workflow runs with wide dataArtifact fan-out (~400/run) OOM both workflow history get and swamp serve boot, crash-looping the scheduler; rollback doesn't help (state-triggered, not release-triggered)

Show user:<name> instead of user:<id> in grant list output

Reusable long-lived invite link: one URL to bring people into the swamp