Inspect — ask a stack what is true now

txco trace answers "what just happened?". txco inspect answers "what is the current state, and why?": it asks the tenant's own rules, because only the stack knows how its state is keyed. The question becomes an ordinary event, @src == "inspect", and the rule that knows the answer replies with a card.

txco inspect crm company openai                 # the card, rendered
txco inspect crm company openai --json          # the card document
txco inspect crm company openai --arg window=30d

The arguments are a stack, then optionally a noun and an id, then any --arg k=v. Over the admin API the same question is POST /v1/tenants/{tenant}/inspect with {"stack", "noun", "id", "args"}. (txco package inspect is a different verb: it reads a package’s manifest.)

Answering

The chassis routes the question to the tenant’s _inspect stack. A rule there gates on the stack and noun it can explain, and writes the card at ._inspect.card:

# OPS/_inspect/100/company.txcl
WHEN @src == "inspect" && @inspect.stack == "crm" && @inspect.noun == "company"
  EMIT ._inspect.card = &object(
         "title", "Company",
         "sections", &array(&object(
           "title", "Request",
           "rows", &array(&array("Id", @inspect.id))
         ))),
       @halt = true

The question is at @inspect.stack, @inspect.noun, @inspect.id and @inspect.args.<k>. The chassis writes those, so a rule cannot be fooled about which tenant asked or what.

A card is {title, sections: [{title, rows: [[label, value], …]}], raw}. A value may be any JSON. raw is optional: the domain JSON behind the card, for --json readers. Real inspectors look things up first — txco://kv/get a snapshot, txco://read-file a manifest, a nano-op that shapes the card.

When no rule answers (no _inspect stack, or none for that stack and noun), the answer is 404 no_inspector.

A package that ships an _inspect/ stack makes every install of it debuggable.

Example

examples/inspect-hello — an inspector that echoes the question back as a card.