Yichus / Reference / API MCP tools
api_composition_proposal
Record authored structural changes against an exact checked source-composition snapshot. The proposal JSON must carry composition-proposal-1 or -2, baselineSnapshot, nonempty intent and 1-128 add/remove definition or relation operations; -2 also accepts add-export/remove-export {binding} and add-import/remove-import {package, binding}, where package is the importing package and binding the qualified imported definition. The composition-proposal-read-2 overview assesses declarations from the baseline's typed exports and imports: each cross-package source-reference relation, removed definition and import left unused names its required export/import edits as present, authored or missing, and any package import cycle. An added relation that already exists is already-present with its baseline relation IDs. The overview's impact lists, for each existing definition whose outgoing relations change, its direct and transitive baseline consumers; page them with {scope: impact}. This tool recompiles all sources and rejects stale snapshots, unknown identities, duplicate definition targets, relation removals or declaration edits, and inconsistent operations. Repeated added relations can represent distinct future occurrences. The bounded proposal page is an authored plan, never checked source or a behavior proof. Optional after_sources compiles a second full program and returns both structural observations and a bounded actual diff that exposes unexpected changes. Observations are relative to the supplied source sets: a package in only one of sources and after_sources is observed as added or removed, so its definitions appear as observed removals or unplanned changes; an unavailable channel leaves its steps inconclusive. No result proves behavioral equivalence or architectural quality. Use api_organize composition read to obtain the baseline snapshot and checked relation IDs before proposing removals.
Kind: CompositionProposal. Family changes: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.
CLI: yichus organize composition-proposal — one authored, snapshot-bound structural proposal through CLI, MCP and WebMCP; optional actual sources provide structural observations only.
Parameters
sources(required, array) — Complete baseline [{fileName, source}] Bosatsu source set; compiled to check baselineSnapshot.proposal(required, object) — Authored composition-proposal-1 or composition-proposal-2 JSON object with baselineSnapshot, intent and operations; a JSON-encoded string is also accepted.read(optional, object) — Optional bounded {scope: overview, limit?, cursor?, expectedBaseline?}, {scope: impact, limit?, cursor?, expectedBaseline?} or {scope: witness, id, expectedBaseline?}; defaults to overview. Cursors are bound to the proposal and scope.after_sources(optional, array) — Optional complete second [{fileName, source}] Bosatsu source set for structural observation only. Supply every package: a package on only one side is observed as added or removed, not skipped.diff_read(optional, object) — With after_sources: optional bounded actual composition diff overview, packages, or exact witness request. Defaults to overview, so unexpected changes remain visible.
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.