Describe

mantle describe <target> <manifest>... compiles manifests and prints JSON. An explicit target is required; use the generation target because hashes include the dialect. The command writes no project files. --diff <old.json> prints a JSON array of changes against a saved report.

describeApp(plan) and diffApp(a, b) are exported by @aotter/mantle/describe. The AppDescription TypeScript type is the contract. targetHash(plan, id) is also exported by @aotter/mantle/target-hash. These exports use no Node APIs and load no SQL parser.

The schemaVersion 1 report contains:

• access: plan.access.userFields, mapping declared user fields to their type, multiplicity and optional enum.
• targets: MCP Tool-shaped objects with name, title, description, inputSchema, annotations and _meta. View and Procedure names follow MCP naming. Route inputs are plain objects with a name selector for known dispatcher variants; their variants retain the selected input schemas.

Each target’s _meta contains:

• id: view:<name>, procedure:<name>, rest:<METHOD> <path> or admin:<METHOD> <path template>. Parameters use :name; Admin paths are relative to the API base. Publishing ids use procedure:<schema>.<verb>; media tool ids use admin:tool:<name>.
• targetHash: a hash of behavior, inputs, requirements, restrictions, related Schema definitions, surfaces, Triggers and reachable hooks. Optional lowering caches do not affect it. Ref registration keys are included; application-owned handler implementations are not.
• scope and restrict: per-Schema owner and user-field terms. Owner terms use owner; user-field terms name their column, field and type.
• readOnly: true only when all reachable statements are reads. Ref handlers and routes without known dependencies are false.
• trustedOnly, opaque, unscopedReads: trusted-only execution, ref-handler opacity and reads of Schemas without row scope. Opaque code conservatively includes every Schema available to its Store.
• surfaces and triggers: every declared exposure and each Trigger’s id and source. Views include admin for developer previews.
• requires: conjunctive predicates in all and an optional guard name. Admin-only targets include the admin gate.
• variants: each selectable target’s id, input schema, requirements, flags and row policies. Route restrictions contain terms common to all variants.

Descriptions contain no SQL or rows. They describe declarations; application router additions and optional module mounting remain application-owned.

Diff records contain id, field, direction and optional before/after. Removing a scope or restrict term widens access; adding one narrows it. Reading another Schema, dropping requirements, adding surfaces or Triggers, removing readOnly or trustedOnly, or enabling opaque or unscopedReads widens access. Variants are compared separately. Adding a target widens; removing one narrows. Every input schema change is changed, as are other behavior changes. Directions describe individual changes, not an overall proof when several fields change.