Skip to main content
← Back to list
01Issue
BugOpenSwamp CLIPublic
AssigneesNone

Relationships

#2117 Published model documentation is incomplete or inaccurate across different schema layouts

Opened by josh · 9/11/2026

Observed behavior

The Models section at https://swamp-club.com/extensions/@josh/sprites is populated. For extension version 2026.09.11.3 it displays all six models, global arguments, 80 methods, and 10 file entries. The missing entries discussed here are specifically the resource outputs declared under each exported model.resources object. These are separate from model methods and files.

The website shows no Resources sections for .3. A fresh swamp extension info @josh/sprites --json check reports latestVersion 2026.09.11.3 and an empty contentMetadata.models[].resources array for each of the six models.

Change between releases

Resource entries appeared in the preceding 2026.09.11.2 release, although earlier inspection found omissions there too. In .3, our extension change replaced resource schema references with direct z.object expressions inside the exported model objects. The source change is commit fcc0b7d8 in https://github.com/joshuadavidthomas/swamp-extensions; the preceding release is commit eaf936e0. The extension version changed; model versions remained 2026.09.11.1.

Local extraction of the .3 source reported 74 resources, 80 methods, and 12 files. The push dry run also succeeded. Those local checks did not predict the published result: resource entries that appeared in .2 disappeared in .3. We published this regression in our extension while trying to make the contracts visible to metadata extraction.

Other concrete discrepancies in .3

  • Source: sprites/extensions/models/service.ts declares put.arguments.service as z.object(...) without an outer .optional(). Website: fn put(service?: object, duration?: string). Registry JSON: service.required is false.
  • Registry JSON gives every model an empty type string. The website labels the model sections with source file paths, such as extensions/models/service.ts; the model sections themselves are present.
  • Website and registry JSON show connector.updatePolicy with the description "Replace this connection". This is a truncated description.
  • The website shows one organization file entry and nine sprite file entries, for 10 total; local extraction reported 12.

The sprite.create signature did improve in .3: the website now lists config, environment, url_settings, labels, wait_for_capacity, and runtime. The metadata is partially correct, not empty.

Reproduction and expected result

Inspect the .3 source at the commit above, especially exported model.resources in sprites/extensions/models/service.ts. Compare it with swamp extension info @josh/sprites --json and the rendered Models section. Compare the .2 and .3 source commits to see the schema-layout change.

Expected: the published metadata should include the declared resource outputs and accurately describe required method arguments and file entries.

Diagnosis limits

The source-layout change and the published regression are observed. A metadata extraction problem is suspected, but the exact failing component and parsing mechanism have not been isolated. We have not established that nested optional fields cause the wrong required flag, that refinements cause omitted arguments, or that apostrophes cause description truncation. The original report stated those suspected mechanisms too strongly. This report concerns documentation metadata; these observations do not establish a runtime resource-writing failure.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/11/2026, 10:14:23 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

josh commented 9/11/2026, 10:45:25 PM

Release history: three source layouts, three published results

The .1 release is important context missing from the initial report. These are extension versions 2026.09.11.1, 2026.09.11.2, and 2026.09.11.3. All six model versions remained 2026.09.11.1.

.1: imported collections and helper-built entries

Source commit: e730312a.

In sprites/extensions/models/sprite.ts, the exported model assembled methods, resources, and files by spreading imported collections, for example ...spriteMethods, ...spriteResources, and ...execFiles. Other models used helper calls to build entries. For example, checkpoint.ts declared state: resource(CheckpointRecord, ...) and create: method(description, argumentsSchema, ...). Global arguments referenced shared or composed schemas.

The publisher observed the website model documentation as empty in this release. We do not have a field-by-field .1 registry snapshot attached here, so this observation should not be read as a claim that every JSON field or the entire extension page was empty.

.2: literal entries, but schemas still referenced elsewhere

Source commit: eaf936e0.

We expanded the imported collections and helper-built entries into explicit method, resource, and file objects in each model file. The public schemas were still partly indirect. For example, checkpoint.ts changed state: resource(...) into state: { schema: CheckpointRecord, description: ..., lifetime: ..., garbageCollection: ... }. Its globalArguments still referenced CheckpointArgsSchema; resource schemas still referenced CheckpointRecord and CheckpointEvents. Method argument definitions also retained shared schema references in places.

The website then displayed methods, arguments, resource entries, and file entries. This was a partial improvement over .1. Earlier inspection found missing final resource/file entries, sprite.create displayed with id instead of its actual create arguments, service.put.service marked optional, and truncated descriptions. These are observations from inspecting .2 before .3 replaced it as latest, not a newly captured .2 response.

.3: schemas expanded inside the literal entries

Source commit: fcc0b7d8.

We replaced remaining public schema references and composition with direct Zod definitions inside the exported model. For example, checkpoint.ts now has globalArguments: z.object({...}) and state: { schema: z.object({...}), ... }; the checkpoint fields and nested Sprite identity fields are written there directly. The same expansion covered public method arguments and resource schemas across all six models. We also added a source validation gate against indirect public contracts.

The website now shows the corrected sprite.create arguments: config, environment, url_settings, labels, wait_for_capacity, and runtime. It still shows all six models, 80 methods, and 10 file entries. However, resource outputs that appeared in .2 no longer appear: current registry JSON has six empty resources arrays, and the rendered page has no Resources sections. The optional service argument and truncated descriptions also remain wrong.

What this comparison establishes

Making entry objects explicit in .2 exposed documentation absent in .1. Expanding the schemas themselves in .3 corrected at least one method signature while regressing resource-output visibility. Therefore neither refactor fully solved the published metadata problem. These releases changed multiple things; they are evidence of source-layout-sensitive behavior, not an isolated proof of a particular parser bug. A minimal reproduction should vary these layouts separately.

Sign in to post a ripple.