/commands

A slash command is a shell alias with a prompt in it. That is the honest description of the feature, and it is why this unit is short.

The idea underneath is the counterweight to terms 4 and 8. Those made instructions resident: they enter every turn and are paid for on every turn, whether that turn needed them or not. A command is the opposite arrangement. Its body sits on disk costing nothing until something invokes it, and then it costs its full price for exactly one turn.

Neither is better. They are two positions on one dial, and the dial is how often the instruction will be needed. Term 20 automates the same decision; this is the manual version, where a human decides by typing a name.

The mechanism

src/commands.ts splits a command into a one-line summary that is always resident, because the model has to know the command exists, and a body that is not. compare runs both arrangements over a sequence of turns and reports what deferring bought.

The receipt

artifacts/09-commands.json:

3 commands
  resident cost      33 tokens/turn (the one-line summaries)
  if all resident   574 tokens/turn (every body, every turn)

typo -> no command /extarct. Known: /extract, /audit, /refuse

called on   0% of turns  on-demand   660  resident 11480  saved   94.3%
called on  50% of turns  on-demand  4940  resident 11480  saved     57%
called on 100% of turns  on-demand  9220  resident 11480  saved   19.7%

The field that could not be true

The first version of compare returned a backfired flag, for the case where loading on demand costs more than keeping everything resident. The tension with terms 4 and 8 made that feel obviously possible.

It is not possible. On-demand pays the summaries plus one body. Resident pays the summaries plus every body. The first can never exceed the second, so the flag was a branch nobody could reach — written from an assumption rather than from the arithmetic, and the sort of thing this repository keeps a census about.

What is real is break-even, and it needs the catalogue shrunk to one command:

one command in the catalogue, so there is nothing to defer past:
called on  90% of turns  on-demand  7924  resident  8780  saved    9.7%
called on 100% of turns  on-demand  8780  resident  8780  saved      0%  BREAK-EVEN

With a single command called on every turn the two arrangements are identical and the machinery is ceremony. The demo now exits non-zero if no sweep point reaches break-even, because a flag nobody has watched become true is a flag nobody has tested.

Break it first

mutation                                   tests                 demo
invoking a command costs nothing extra     3 failed | 7 passed   exit 1
bodies never charged in the comparison     2 failed | 8 passed   exit 1
break-even never reported                  1 failed | 9 passed   exit 1
an unknown command returns an empty body   1 failed | 9 passed   exit 0

The last row is the one worth sitting with. A typo returning an empty body rather than an error is silently a no-op turn: the model gets the summaries and no instruction, produces something plausible, and nothing anywhere says a command failed to load. The tests catch it and the demo does not, because the demo never makes a typo on purpose except in the line that prints the refusal.

Where it overlaps

Line B is instruction packaging, and this is the rung where a package stops being resident. Term 4 and term 8 are the resident rungs below; term 14 makes the trigger semantic instead of typed; term 20 decides automatically. Line A is context economics, and this unit is the first place in the course where the answer to "what does it cost" is "nothing, until you ask".