Sidequest: The Double Star, or How One Bag of Extras Gets Poured Into Three Calls

The thing itself

Those two lines are the same trick under two names. You fill a small bag of optional extras first, and then the double star at the end of a function call tips the whole bag into that call, as if every item in it had been typed out by hand.

Why it showed up tonight

You were building the server side of the D-09 build stamp. The phone has been sending its build number with every request for a while, and Capture has been ignoring it. The session's job was to catch that number when the app creates a capture and write it into the new column.

The app's door into Capture, the multipart door, already had a bag called system kwargs. It held two possible extras: the sender's name when the capture is a text message, and the system card details when a machine is reporting something. The build stamp needed to ride along too. Once the bag held the build number as well, the name "system" was wrong, since the build number has nothing to do with system cards. So in that door the session renamed the bag to door kwargs, as in "extras for this door", and added the build stamp to it.

That is why you saw both names. The other door, the JSON one the web dashboard uses, never gets a build header from the phone, so its bag is still called system kwargs. Same trick, two doors, two names. The Codex review read the diff and came back clean.

The mental model

Think of a capture being saved as a form with a lot of fields. Some fields are always there: the text, the lane, the source. Others only exist sometimes. A text message has a sender. A machine message has a system contract. A capture from a new enough app has a build number. Most captures have none of these.

You could write it out the long way, with an if-statement at every save: if there is a sender, pass it, if there is a build, pass that, in every combination. The trouble is that the multipart door has three separate save calls: one for a voice capture that transcribed, one for a voice capture still waiting on transcription, and one for plain text. Three calls, three optional extras, every combination. That is how one of the three calls quietly ends up forgetting the build number.

The bag fixes that. The door works out the extras once, near the top: is there a sender, is this a system message, did the phone say which build it is. Each one that turns out to be real goes into the bag. Each one that is missing or broken stays out. After that, all three save calls end with the same double-star bag. Add a fourth extra next month and you add it in one place, and all three calls get it.

The useful part is that an extra that stays out is truly absent, not a blank. When the save function receives nothing for the build number, it uses its own default and writes nothing. That is the rule the session wanted: a missing or malformed header is dropped and never fails the capture. The bag is the tool that enforces it. If the phone sends garbage, the parser hands back nothing, the bag stays empty, and the save carries on as if the header had never been sent.

A packed lunch is a fair analogy, as far as it goes. You pack once in the morning and the kid takes the same box to whichever classroom. No banana today means there is no banana in the box, not a box labelled "banana: none". The analogy breaks at this point: in Python, if the bag held a key the save function did not know about, the call would crash on the spot. So the bag is less a lunch box and more a set of named sockets that must all fit. That strictness is useful. A typo in a field name fails in the tests instead of disappearing into the database.

Where else it lives

You do not have to go far. The function at the other end of those calls, the one in Capture's database layer that writes the actual row, does the same thing one level down. When it builds the insert for the new captures table, it only adds the sender column if a sender was actually given. Otherwise it adds an empty bag and the column is left out. So the rule that "absent stays absent" holds from the moment the request arrives until the row lands in the database.

It also explains why the session's 24 failing tests changed nothing in production code. The new door now reads request headers to fill the bag, and the old test requests were fakes with no headers at all. Once they were given a set of headers, even an empty one, they passed. The bag itself was fine. The tests were just turning up without the right paperwork.

If you remember one thing: the double star is a bag packed once and tipped into every save call, so an optional extra like the build stamp gets added in one place, and when it is missing it is simply absent rather than an error.