`api_report_brief`

Package the report's derived facts (headline, map, guarantees, needed, facts) with constant writing instructions, ready to hand to any LLM that should produce an orientation narrative. The output is fully deterministic: the engine prepares the data and names the task; the prose is the consumer's. Use api_report for the full artifact.

Kind: ReportBrief. Origin: Yichus/Mcp::catalog.

CLI: none — the report's brief form (ProgramReport.briefJson) is available through `yichus call api_report_brief`; the named CLI command prints the full report with `api report --detail summary`.

Parameters

sources (required, array) — JSON array of {fileName, source} Bosatsu files for the module.
instances (optional, string) — Deployment topology: 1 for a single engine instance, many (default) for multiple instances sharing one DB.

Example

This response was produced by calling this tool with the displayed request when these docs were generated. Analysis examples use the owner-scoped notes specimen; scaffold examples supply a resource specification.

Request

{
  "sources": [
    {
      "fileName": "notes-api.bosatsu",
      "source": "package Demo/Service/NotesApi\n\n# Owner-scoped notes API. One row per caller, keyed by Principal.user_id.\n# `yichus api verify` / api_access_check prove the scoping from Matchless IR.\n\nfrom Yichus/IO import IO, flat_map\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_read, db_write, db_delete\nfrom Yichus/Service import handler, route, service_def, ReadPerm, WritePerm, DeletePerm\n\nexport (notes_api, access_rules, Note())\nexposes (Yichus/Access, Yichus/Service)\n\nstruct Note(title: String)\n\naccess_rules = AccessSpec([\n  AccessRule(\"notes\", OwnerScoped),\n])\n\ndef notes_table(db: Db) -> Table[List[Note]]:\n  table(db, \"notes\")\n\ndef list_notes(db: Db, p: Principal) -> IO[List[Note]]:\n  Principal(uid, _) = p\n  db_read(notes_table(db), uid)\n\ndef put_notes(db: Db, p: Principal, items: List[Note]) -> IO[List[Note]]:\n  Principal(uid, _) = p\n  db_write(notes_table(db), uid, items)\n\ndef add_note(db: Db, p: Principal, item: Note) -> IO[List[Note]]:\n  Principal(uid, _) = p\n  items <- flat_map(db_read(notes_table(db), uid))\n  db_write(notes_table(db), uid, [item, *items])\n\ndef clear_notes(db: Db, p: Principal) -> IO[Unit]:\n  Principal(uid, _) = p\n  db_delete(notes_table(db), uid)\n\nnotes_api = service_def(\n  \"notes\",\n  [\n    route(\"/notes\", handler(\"list_notes\", list_notes), [ReadPerm(\"notes\")]),\n    route(\"/notes/put\", handler(\"put_notes\", put_notes), [WritePerm(\"notes\")]),\n    route(\"/notes/add\", handler(\"add_note\", add_note), [ReadPerm(\"notes\"), WritePerm(\"notes\")]),\n    route(\"/notes/clear\", handler(\"clear_notes\", clear_notes), [DeletePerm(\"notes\")]),\n  ]\n)\n"
    }
  ],
  "instances": "1"
}

Response

{
  "ok": true,
  "tool": "api_report_brief",
  "artifactClass": "program-report-brief-1.0",
  "instructions": "You are writing an orientation briefing for a program you have never seen, from the attached data object. Ground every sentence in that data: use only these facts; never invent names, counts, causes, or guarantees; if something is not in the data, say it is not established. Write four short sections: (1) What this is — one paragraph from headline.class and headline.counts. (2) The shape — walk map.nodes zone by zone (surface = entry points, work = logic, state = tables and shared cells, specs = declared patterns and proofs), naming the largest nodes by size and how map.edges connect them; map.truncated counts nodes and edges elided by deterministic caps, so mention those counts and treat any other absence as meaningful. (3) What is proven — restate each guarantees[] claim with its status, under data.topology. (4) What is unfinished — every node whose status is unrouted, undeclared, or needed, every cond reference, and every needed[] artifact with its because. Refer to structures by their node id.",
  "data": {
    "topology": "single-instance",
    "proven": true,
    "headline": {
      "class": "crud-api",
      "counts": {
        "routes": 4,
        "bindings": 4,
        "tables": 1,
        "cells": 0,
        "flows": 0,
        "abstractions": 1,
        "packages": 1
      },
      "liminal": {
        "unrouted": 0,
        "undeclared": 0,
        "needed": 1
      }
    },
    "map": {
      "nodes": [
        {
          "id": "needed:FrontendSpec",
          "zone": "surface",
          "size": 0,
          "status": "needed"
        },
        {
          "id": "route:/notes",
          "zone": "surface",
          "size": 1
        },
        {
          "id": "route:/notes/add",
          "zone": "surface",
          "size": 1
        },
        {
          "id": "route:/notes/clear",
          "zone": "surface",
          "size": 1
        },
        {
          "id": "route:/notes/put",
          "zone": "surface",
          "size": 1
        },
        {
          "id": "abstraction:notes_table",
          "zone": "work",
          "size": 5
        },
        {
          "id": "binding:add_note",
          "zone": "work",
          "size": 2,
          "cond": [
            "guarantee:rmw-transactions"
          ]
        },
        {
          "id": "binding:clear_notes",
          "zone": "work",
          "size": 1
        },
        {
          "id": "binding:list_notes",
          "zone": "work",
          "size": 1
        },
        {
          "id": "binding:put_notes",
          "zone": "work",
          "size": 1
        },
        {
          "id": "table:notes",
          "zone": "state",
          "size": 4,
          "status": "violated",
          "cond": [
            "invariant:race-free:notes"
          ]
        }
      ],
      "edges": {
        "routes_to": [
          [
            "route:/notes",
            "binding:list_notes"
          ],
          [
            "route:/notes/add",
            "binding:add_note"
          ],
          [
            "route:/notes/clear",
            "binding:clear_notes"
          ],
          [
            "route:/notes/put",
            "binding:put_notes"
          ]
        ],
        "reads": [
          [
            "binding:add_note",
            "table:notes"
          ],
          [
            "binding:list_notes",
            "table:notes"
          ]
        ],
        "writes": [
          [
            "binding:add_note",
            "table:notes"
          ],
          [
            "binding:put_notes",
            "table:notes"
          ]
        ],
        "deletes": [
          [
            "binding:clear_notes",
            "table:notes"
          ]
        ],
        "covers": [
          [
            "needed:FrontendSpec",
            "route:/notes"
          ],
          [
            "needed:FrontendSpec",
            "route:/notes/add"
          ],
          [
            "needed:FrontendSpec",
            "route:/notes/clear"
          ],
          [
            "needed:FrontendSpec",
            "route:/notes/put"
          ]
        ]
      }
    },
    "facts": [
      "surfaces: tables, routes, shared-cells",
      "4 route(s), 4 handler(s)",
      "1 table(s)",
      "1 shared cell(s)",
      "notes: OwnerScoped (holds, row Note)",
      "add_note: read-modify-write on notes",
      "every op on notes keys by the caller",
      "1 missing declaration(s); call api_add_artifact"
    ],
    "needed": [
      {
        "artifact": "FrontendSpec",
        "because": "4 route(s) are declared but no FrontendSpec binding selects them",
        "unlocks": "api_frontend"
      }
    ],
    "guarantees": [
      {
        "id": "compiles",
        "claim": "parses and type-checks",
        "status": "proven"
      },
      {
        "id": "access-spec-declared",
        "claim": "an AccessSpec binding declares every table's policy",
        "status": "proven"
      },
      {
        "id": "access-coverage",
        "claim": "every DB operation touches a declared resource",
        "status": "proven"
      },
      {
        "id": "access:notes",
        "claim": "every DB operation on \"notes\" keys by the caller's Principal.user_id",
        "status": "proven"
      },
      {
        "id": "route-permissions",
        "claim": "declared route permissions equal handler effects recovered from the IR",
        "status": "proven"
      },
      {
        "id": "route-authority",
        "claim": "Route authority declarations are enforceable",
        "status": "proven"
      },
      {
        "id": "rmw-transactions",
        "claim": "add_note reads then writes \"notes\"",
        "status": "warning"
      },
      {
        "id": "integrity",
        "claim": "bounded interleaving over shared cells is race-free",
        "status": "warning"
      }
    ]
  }
}

Run tools in the browser: api-mcp.html?webmcp=1.

Read the result according to this tool’s scope: static checks, bounded execution checks, and descriptive diagrams answer different questions. A successful call is not a general approval of the program. The safety and permissions guide compares the checks and provides editable ownership, guard, and role examples.