Module authoring 

The authoring interface a coding harness uses to build a session spec.

A harness (a coding agent, an IDE, a CLI wizard) edits agent.json on the user’s behalf. These operations tell it what can be written, what is wrong with the document, and which decisions are still the user’s to make:

• catalog lists the vocabulary: voices, guard atoms, policies, tool bindings, resume policies, question rules and diagnostic codes.
• check validates a document and reports structured Diagnostics. Each has a JSON pointer and, where the repair is mechanical, a Fix expressed as JSON-patch operations.
• plan lists the open decisions as Questions. Every option carries the patch that records it.
• answer applies chosen options. It plans again before each answer, so every patch is computed against the current document.
• apply_patch applies JSON-patch operations (RFC 6902 add, replace, remove) atomically.

All of them take the document as a JSON value, so a document that does not deserialize still gets diagnostics.

Fixes in one CheckReport are each computed against the checked document. Apply one, then check again: two fixes from the same report can touch the same array.

use gemini_adk_fluent_rs::spec::authoring::{self, Answer, Decisions};
use serde_json::json;

let doc = json!({ "name": "", "instruction": "Answer questions about opening hours." });
let plan = authoring::plan(&doc, &Decisions::new());
assert_eq!(plan.questions[0].id, "name");

let answered = authoring::answer(
    &doc,
    &[Answer::with_value("name", json!("hours-line"))],
    &Decisions::new(),
)
.unwrap();
assert_eq!(answered.spec["name"], "hours-line");

Structs

Answer

One answer to a Question.

AnswerOption

One way to answer a question.

Answered

The result of answer.

Catalog

The vocabulary a harness may write. The full document shape is the spec’s JSON Schema (SessionSpec::json_schema, adk spec schema).

CatalogEntry

One authorable item: its name, what it means and an example.

CheckReport

The result of check.

Diagnostic

One problem found by check.

Fix

A mechanical repair for a diagnostic.

PatchError

Why a patch could not be applied.

Plan

The result of plan.

Question

A decision the document leaves open.

Enums

AnswerError

Why answers could not be applied. Nothing is applied when any answer fails.

PatchOp

One JSON-patch operation (RFC 6902 subset). path is a JSON pointer.

QuestionKind

How a question is answered.

Severity

How serious a diagnostic is.

Constants

ANSWER_PLACEHOLDER

The placeholder an option’s patch uses for the user’s value. A string equal to it is replaced by Answer::value.

AUTHORING_VERSION

Version of the authoring interface. Bumped when an operation’s output changes incompatibly.

SIGNALS_EXTRACTOR

Name of the extractor that question and fix patches add boolean caller signals to (confirmations, intents).

Functions

answer

Apply answers in order. Before each one the document is planned again, so a patch never comes from a stale plan.

apply_patch

Apply ops in order to a copy of doc. Either every operation applies or the document is returned unchanged inside the error.

catalog

The authoring vocabulary.

check

Validate doc and report structured diagnostics.

check_str

check the text of a spec file. Text that is not JSON gets an invalid_json diagnostic with its line and column.

plan

The open decisions in doc, skipping question ids in decisions.

Type Aliases

Decisions

Answered question ids, mapped to the chosen option value. A harness stores this next to the spec and passes it back so answered questions are not asked again.