@llm4ts/shell 2.15.0 → 2.16.0

package/kits/soap-ace/README.md

@@ -14,15 +14,56 @@ source) and shares nothing with this kit.
 
 ## Status
 
-| Piece                                              | State    |
-| -------------------------------------------------- | -------- |
-| Strict XML reader (`flows/lib/soap/Xml.ts`)        | done     |
-| WSDL 1.1/2.0 + XSD catalog (`Wsdl.ts`, `Xsd.ts`)   | done     |
-| `demo-bank-soap` fixture                           | WSDL/XSD |
-| `soap-discover` flow and operation classification  | pending  |
-| Masking, auth profile, transport, sample authoring | pending  |
-| Analysis, REST design, OpenAPI projection          | pending  |
-| `ace12-rest` pack, scaffold, `soap-epic`           | pending  |
+| Piece                                                                    | State |
+| ------------------------------------------------------------------------ | ----- |
+| Strict XML reader, WSDL 1.1/2.0 + XSD catalog                            | done  |
+| `soap-discover` flow and operation classification                        | done  |
+| Masking, auth profile, transport, sample authoring                       | done  |
+| Analysis, REST design, OpenAPI projection                                | done  |
+| `ace12-rest` pack, scaffold, `soap-epic`                                 | done  |
+| `soap-explore`: the discovery half in one command                        | done  |
+| `demo-bank-soap` fixture ([runbook](fixtures/demo-bank-soap/RUNBOOK.md)) | done  |
+
+## Quick start: soap-explore
+
+One command from a WSDL to a design draft, the way SoapUI turns a WSDL into
+a project. It stops only where a person decides, and a rerun continues where
+it stopped:
+
+```bash
+llm4ts run soap-explore --repo ~/work/conti-analysis ./wsdl/ContiService.wsdl   # or an https URL
+# write .llm4ts/soap/<service>/auth.json: at least {"environment": "test"}
+# review operations.md, set Status: confirmed
+llm4ts run soap-explore --repo ~/work/conti-analysis                             # continue
+```
+
+| Step     | What happens                                                                                                                                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| discover | `catalog.json`/`.md`, `operations.md` with proposed classes (as `soap-discover`)                                                                                                                                                |
+| requests | `samples/<op>/happy-path.request.yaml` for **every** operation, example values from the XSD                                                                                                                                     |
+| probe    | calls the **read** operations once, producers first: the IBAN `cercaConti` returns is what `dettaglioConto` is called with. Live values stay in memory; the request file on disk carries the masked one. Mutating: never called |
+| evidence | `analysis/<op>.md`, `design/mapping.json`/`.md`                                                                                                                                                                                 |
+| design   | the reasoning seat drafts `design/api-design.md`, `check`, one `revise` round when errors remain; an existing design is only checked; `--no-design` skips                                                                       |
+| report   | `explore.md`: per operation the probe decision and result, the chained values, the design state, and the next command for every gap                                                                                             |
+
+**Who may be called.** Without `auth.json` nothing is called (explore never
+writes it: the environment label is yours to declare). With `operations.md`
+confirmed, its `read` operations are called. Before confirmation, an
+operation is called only in dev or test, and only when the file still lists
+it as `read`, the name heuristic says `read`, and the judgment seat
+(`LLM4TS_JUDGMENT_PROVIDER`) answers `read` with an `act` decision; without
+a judgment seat, confirm first. uat always needs confirmation.
+
+**Files it owns.** A request explore writes starts with a `# soap-explore:
+generated` line and is regenerated when probed again. Delete that line to
+own the file: explore then sends it as written and never touches it.
+`--refresh` calls the probed operations again; everything else is kept.
+
+Approvals stay human: `Status: confirmed` in `operations.md`,
+`Status: approved` in `api-design.md`. Then `soap-design "openapi"` and
+`soap-epic` as below. The individual flows remain for everything past the
+first pass: more scenarios per operation (`soap-sample "propose <op>"`),
+mutating calls, SoapUI import, design revisions.
 
 ## soap-discover
 

package/kits/soap-ace/fixtures/demo-bank-soap/RUNBOOK.md

@@ -16,6 +16,22 @@ cd ~/work/conti-analysis
 The analysis repository holds `.llm4ts/soap/<service>/`: catalog, samples,
 analysis, design. The ACE repository receives the contracts and the code.
 
+## Fast path: soap-explore
+
+Steps 1 to 4 in one command, rerun after each decision:
+
+```bash
+llm4ts run soap-explore --repo . ./wsdl/ContiService.wsdl   # discover, requests, report
+# write auth.json (step 2), review and confirm operations.md
+llm4ts run soap-explore --repo .                            # probe reads, analyse, draft the design
+```
+
+Read `.llm4ts/soap/<service>/explore.md` after each run: it lists what was
+called, what was not and why, and the next command. On the fixture:
+`LLM4TS_SOAP_STUB=<kit>/fixtures/demo-bank-soap/responses`. The steps below
+are the same work one command at a time, and what to use past the first
+pass.
+
 ## 1. Discover
 
 ```bash

package/kits/soap-ace/flows/lib/soap/Call.js

@@ -69,7 +69,7 @@ export const callOperation = (options) => Effect.gen(function* () {
             detail: `no auth profile; write ${`.llm4ts/soap/${service}/auth.json`} with at least {"environment": "dev"}`
         });
     }
-    const request = yield* readRequestFile(workspace, catalog, service, operation.name, name);
+    const request = options.request ?? (yield* readRequestFile(workspace, catalog, service, operation.name, name));
     const issues = [
         ...request.readIssues,
         ...validateInstance(catalog, input, request.body)
@@ -130,6 +130,7 @@ export const callOperation = (options) => Effect.gen(function* () {
     // which quote values) is read from the masked, security-stripped tree:
     // nothing unmasked reaches the exchange.
     let fault;
+    let payload;
     if (parsedResponse._tag === "None") {
         responseIssues.push({
             path: "(response)",
@@ -148,11 +149,14 @@ export const callOperation = (options) => Effect.gen(function* () {
         }
         else if (operation.output !== undefined) {
             const output = elementByName(catalog, operation.output);
-            const payload = read.value.payload;
-            if (output !== undefined && payload !== undefined) {
-                responseIssues.push(...instanceFromXml(catalog, output, payload).issues);
+            const masked = read.value.payload;
+            if (output !== undefined && masked !== undefined) {
+                responseIssues.push(...instanceFromXml(catalog, output, masked).issues);
+                const live = yield* readEnvelope(stripSecurity(parsedResponse.value)).pipe(Effect.option);
+                if (live._tag === "Some" && live.value.payload !== undefined)
+                    payload = { live: live.value.payload, masked };
             }
-            else if (payload === undefined) {
+            else if (masked === undefined) {
                 responseIssues.push({ path: "(response)", detail: "empty Body" });
             }
         }
@@ -182,5 +186,5 @@ export const callOperation = (options) => Effect.gen(function* () {
         masking: mergeReports([maskedRequest.report, maskedResponse.report])
     });
     const path = yield* writeExchange(workspace, service, exchange);
-    return { exchange, path, permission };
+    return { exchange, path, permission, ...(payload === undefined ? {} : { payload }) };
 });

package/kits/soap-ace/flows/lib/soap/Explore.js

@@ -0,0 +1,476 @@
+import * as Effect from "effect/Effect";
+import { schemaPaths, writeAnalyses } from "./Analysis.js";
+import { callOperation, RequestInvalid } from "./Call.js";
+import { elementByName } from "./Catalog.js";
+import { heuristicClass } from "./Classification.js";
+import { blockingIssues, checkDesign, designPaths, parseDesignFile, renderDesignFile } from "./Design.js";
+import { proposeDesign, reviseDesign } from "./DesignProposal.js";
+import { readIfPresent, serviceDirectory, servicePaths } from "./Discover.js";
+import { instanceFromXml } from "./Instance.js";
+import { encodeMapping, mapService, renderMapping } from "./Mapping.js";
+import { collectSeeds, readExchanges, renderRequestFile, samplePaths, seedsForService } from "./Samples.js";
+import { isYamlMap, parseYaml } from "./Yaml.js";
+// soap-explore: the whole discovery half in one pass, stopping only where a
+// person decides. Given a catalog it writes a request for every operation,
+// calls the read operations once in producer-first order (values from one
+// response seed the next request), and reports every gap with the command
+// that closes it. Each step keeps what exists, so a rerun continues.
+//
+// Chained values are live only in memory: the call sends the value the
+// service answered with, the request file on disk carries its masked form.
+export const exploreRequestName = "happy-path";
+/** First line of a request file soap-explore owns; deleting it hands the file to the user. */
+export const exploreMarker = "# soap-explore: generated. Delete this line to keep your edits; soap-explore then leaves the file alone.";
+export const explorePaths = (service) => ({
+    report: `${serviceDirectory(service)}/explore.md`
+});
+/**
+ * Which operations the probe may call. Only reads, ever. A confirmed
+ * operations.md decides alone; before confirmation, a provisional probe needs
+ * dev or test, the file still saying read, the name heuristic saying read,
+ * and the judgment saying read with an `act` decision. `judged` undefined
+ * means no judgment seat is configured.
+ */
+export const probeDecisions = (options) => options.catalog.operations.map(({ name }) => {
+    const skip = (reason) => ({ operation: name, probe: false, reason });
+    if (options.environment === undefined)
+        return skip("no auth.json: nothing is called");
+    const file = options.operations;
+    const listed = file?.classes.get(name) ?? "unclassified";
+    if (file?.confirmed === true) {
+        if (listed === "read") {
+            return { operation: name, probe: true, basis: "confirmed", reason: "confirmed read" };
+        }
+        return skip(listed === "mutating"
+            ? "mutating: never probed"
+            : "unclassified in operations.md: not callable");
+    }
+    if (options.environment === "uat")
+        return skip("uat: confirm operations.md before any call");
+    if (listed !== "read") {
+        return skip(listed === "mutating" ? "mutating: never probed" : "unclassified: confirm operations.md");
+    }
+    const heuristic = heuristicClass(name);
+    if (heuristic.class !== "read") {
+        return skip(`heuristic says ${heuristic.class}: confirm operations.md to call it`);
+    }
+    if (options.judged === undefined) {
+        return skip("no judgment seat (LLM4TS_JUDGMENT_PROVIDER): confirm operations.md to call it");
+    }
+    const judged = options.judged.get(name);
+    if (judged === undefined)
+        return skip("the judgment did not answer: confirm operations.md");
+    if (judged.class !== "read" || judged.decision !== "act") {
+        return skip(`judgment says ${judged.class} ${judged.confidence.toFixed(2)} (${judged.decision}): confirm operations.md`);
+    }
+    return {
+        operation: name,
+        probe: true,
+        basis: "provisional",
+        reason: `provisional read: heuristic and judgment agree (${judged.confidence.toFixed(2)})`
+    };
+});
+// ---------------------------------------------------------------------------
+// Producer-first order
+const fieldName = (path) => (path.split(".").pop() ?? path).replace(/\[\]$/, "").replace(/^@/, "");
+/** Leaf field names of an element; `requiredOnly` drops optional ones and those under optional parents. */
+export const leafNames = (catalog, element, requiredOnly) => {
+    const declared = element === undefined ? undefined : elementByName(catalog, element);
+    if (declared === undefined)
+        return new Set();
+    const paths = schemaPaths(catalog, declared);
+    const optional = paths.filter((path) => path.optional).map((path) => path.path);
+    return new Set(paths
+        .filter((path) => path.leaf &&
+        (!requiredOnly ||
+            (!path.optional &&
+                !optional.some((prefix) => path.path.startsWith(`${prefix}.`) || path.path.startsWith(`${prefix}@`)))))
+        .map((path) => fieldName(path.path)));
+};
+/**
+ * Order `names` so producers run first: A precedes B when a leaf of A's
+ * response is a required input field of B. Kahn's algorithm; ties and cycles
+ * resolve in catalog order.
+ */
+export const probeOrder = (catalog, names) => {
+    const operations = catalog.operations.filter((operation) => names.includes(operation.name));
+    const producers = new Map();
+    for (const consumer of operations) {
+        const needs = leafNames(catalog, consumer.input, true);
+        const links = [];
+        for (const producer of operations) {
+            if (producer === consumer)
+                continue;
+            const gives = leafNames(catalog, producer.output, false);
+            const fields = [...needs].filter((field) => gives.has(field));
+            if (fields.length > 0)
+                links.push({ producer: producer.name, fields });
+        }
+        producers.set(consumer.name, links);
+    }
+    const order = [];
+    const remaining = operations.map((operation) => operation.name);
+    while (remaining.length > 0) {
+        const ready = remaining.find((name) => (producers.get(name) ?? []).every((link) => !remaining.includes(link.producer))) ?? remaining[0];
+        if (ready === undefined)
+            break;
+        order.push(ready);
+        remaining.splice(remaining.indexOf(ready), 1);
+    }
+    return { order, producers };
+};
+/** First value per field name in a response payload. */
+export const payloadSeeds = (catalog, operation, payload) => {
+    const output = operation.output === undefined ? undefined : elementByName(catalog, operation.output);
+    if (output === undefined)
+        return new Map();
+    const seeds = new Map();
+    for (const [key, value] of collectSeeds([instanceFromXml(catalog, output, payload).value])) {
+        if (key === "#text")
+            continue;
+        const name = key.replace(/^@/, "");
+        if (!seeds.has(name))
+            seeds.set(name, value);
+    }
+    return seeds;
+};
+const describeExchange = (exchange) => exchange.fault !== undefined
+    ? `fault ${exchange.fault.code} ${exchange.fault.reason}`
+    : `HTTP ${exchange.response?.status ?? "?"}`;
+const withSeeds = (base, chained, fields) => {
+    const seeds = new Map(base);
+    for (const field of fields) {
+        const value = chained.get(field);
+        if (value !== undefined)
+            seeds.set(field, value);
+    }
+    return seeds;
+};
+export const exploreService = (options) => Effect.gen(function* () {
+    const { workspace, catalog, service } = options;
+    const progress = options.progress ?? (() => Effect.void);
+    const decisions = probeDecisions({
+        catalog,
+        operations: options.operations,
+        environment: options.profile?.environment,
+        judged: options.judged
+    });
+    const probed = decisions.filter((decision) => decision.probe).map((d) => d.operation);
+    const plan = probeOrder(catalog, probed);
+    // The probe calls only operations it decided on, as confirmed reads.
+    const probeFile = {
+        confirmed: true,
+        classes: new Map(probed.map((name) => [name, "read"]))
+    };
+    const serviceSeeds = yield* seedsForService(workspace, catalog, service);
+    const live = new Map();
+    const masked = new Map();
+    // Which operation's response supplied each chained field.
+    const suppliedBy = new Map();
+    const reports = new Map();
+    /**
+     * Write the request when absent; regenerate one explore owns only before
+     * calling it. A file the user owns (no marker line, or the XML form) is
+     * never touched.
+     */
+    const ensureRequest = (operation, chainedFields, notes, regenerate) => Effect.gen(function* () {
+        const paths = samplePaths(service, operation.name, exploreRequestName);
+        const yaml = yield* readIfPresent(workspace, paths.yaml);
+        const xml = yield* readIfPresent(workspace, paths.xml);
+        if (xml !== undefined ||
+            (yaml !== undefined && (!regenerate || !yaml.startsWith(exploreMarker)))) {
+            return "kept";
+        }
+        const text = renderRequestFile({
+            catalog,
+            operation: operation.name,
+            purpose: "happy path",
+            seeds: withSeeds(serviceSeeds, masked, chainedFields)
+        });
+        yield* workspace.write(paths.yaml, [exploreMarker, ...notes, text].join("\n"));
+        return yaml === undefined ? "written" : "regenerated";
+    });
+    for (const name of plan.order) {
+        const operation = catalog.operations.find((candidate) => candidate.name === name);
+        const decision = decisions.find((candidate) => candidate.operation === name);
+        if (operation === undefined || decision === undefined)
+            continue;
+        const listed = options.operations?.classes.get(name) ?? "unclassified";
+        const paths = samplePaths(service, name, exploreRequestName);
+        const recorded = yield* readIfPresent(workspace, paths.exchange);
+        const links = (plan.producers.get(name) ?? [])
+            .map((link) => ({
+            ...link,
+            fields: link.fields.filter((field) => suppliedBy.get(field) === link.producer)
+        }))
+            .filter((link) => link.fields.length > 0);
+        const chainedFields = new Set(links.flatMap((link) => link.fields));
+        if (recorded !== undefined && !options.refresh) {
+            const request = yield* ensureRequest(operation, new Set(), [], false);
+            reports.set(name, {
+                operation: name,
+                listed,
+                decision,
+                request,
+                outcome: { kind: "recorded", detail: "recorded earlier; --refresh calls it again" },
+                chained: []
+            });
+            continue;
+        }
+        const notes = links.length === 0
+            ? []
+            : [
+                `# Chained at probe time: ${links.map((link) => `${link.fields.join(", ")} from ${link.producer}`).join("; ")}.`,
+                "# Personal values appear masked here; soap-explore sent the live ones and never stores them."
+            ];
+        const request = yield* ensureRequest(operation, chainedFields, notes, true);
+        // A file explore owns is sent with the live chained values; the file on
+        // disk keeps the masked ones. A user's file is sent as written.
+        const override = request === "kept" || chainedFields.size === 0
+            ? undefined
+            : yield* parseYaml(renderRequestFile({
+                catalog,
+                operation: name,
+                purpose: "happy path",
+                seeds: withSeeds(serviceSeeds, live, chainedFields)
+            })).pipe(Effect.option);
+        const body = override !== undefined && override._tag === "Some" && isYamlMap(override.value)
+            ? override.value["body"]
+            : undefined;
+        const outcome = yield* callOperation({
+            workspace,
+            catalog,
+            service,
+            operation: name,
+            name: exploreRequestName,
+            profile: options.profile,
+            operations: probeFile,
+            secrets: options.secrets,
+            transport: options.transport,
+            allowMutating: undefined,
+            confirm: () => Effect.succeed(false),
+            ...(body === undefined
+                ? {}
+                : { request: { purpose: "happy path", body, form: "yaml", readIssues: [] } }),
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.random === undefined ? {} : { random: options.random })
+        }).pipe(Effect.result);
+        let result;
+        if (outcome._tag === "Failure") {
+            // A request that did not validate may carry live chained values in
+            // its issue text: report where, never what.
+            const error = outcome.failure;
+            result = {
+                kind: "failed",
+                detail: error instanceof RequestInvalid
+                    ? `not sent, the request does not validate at ${error.issues.map((issue) => issue.path).join(", ")}`
+                    : error.message
+            };
+        }
+        else {
+            const { exchange, payload } = outcome.success;
+            result = {
+                kind: "called",
+                detail: `${describeExchange(exchange)}, ${exchange.response?.elapsedMs ?? 0} ms`,
+                findings: exchange.responseIssues.length
+            };
+            if (payload !== undefined) {
+                for (const [field, value] of payloadSeeds(catalog, operation, payload.live)) {
+                    if (!live.has(field)) {
+                        live.set(field, value);
+                        suppliedBy.set(field, name);
+                    }
+                }
+                for (const [field, value] of payloadSeeds(catalog, operation, payload.masked)) {
+                    if (!masked.has(field))
+                        masked.set(field, value);
+                }
+            }
+        }
+        yield* progress(`${name}: ${result.detail}${links.length === 0 ? "" : ` (chained ${[...chainedFields].join(", ")})`}`);
+        reports.set(name, {
+            operation: name,
+            listed,
+            decision,
+            request,
+            outcome: result,
+            chained: links
+        });
+    }
+    // Every other operation gets a request to edit, seeded with what the
+    // probe learnt (masked), and the reason it was not called.
+    for (const operation of catalog.operations) {
+        if (reports.has(operation.name))
+            continue;
+        const decision = decisions.find((candidate) => candidate.operation === operation.name);
+        if (decision === undefined)
+            continue;
+        const needs = leafNames(catalog, operation.input, true);
+        const request = yield* ensureRequest(operation, new Set([...needs].filter((field) => masked.has(field))), [], false);
+        const recorded = yield* readIfPresent(workspace, samplePaths(service, operation.name, exploreRequestName).exchange);
+        reports.set(operation.name, {
+            operation: operation.name,
+            listed: options.operations?.classes.get(operation.name) ?? "unclassified",
+            decision,
+            request,
+            outcome: recorded === undefined
+                ? { kind: "not-called", detail: decision.reason }
+                : { kind: "recorded", detail: "recorded earlier" },
+            chained: []
+        });
+    }
+    return {
+        decisions,
+        plan,
+        operations: catalog.operations.flatMap((operation) => {
+            const report = reports.get(operation.name);
+            return report === undefined ? [] : [report];
+        })
+    };
+});
+/** analysis/<op>.md for every operation, then design/mapping.json + .md. */
+export const writeEvidence = (workspace, catalog, service) => Effect.gen(function* () {
+    const analyses = yield* writeAnalyses(workspace, catalog, service);
+    const mapping = mapService(catalog);
+    const paths = designPaths(serviceDirectory(service));
+    yield* workspace.write(paths.mapping, encodeMapping(mapping));
+    yield* workspace.write(paths.mappingSummary, renderMapping(mapping));
+    const exchanges = (yield* readExchanges(workspace, service)).length;
+    return { analyses, exchanges };
+});
+/**
+ * The design step: an existing api-design.md is only checked; otherwise,
+ * with evidence and a reasoning seat, draft it, check it, and revise once
+ * when errors remain. The file is always written as proposed.
+ */
+export const designStep = (options) => Effect.gen(function* () {
+    const { workspace, catalog, operations } = options;
+    const analyses = options.evidence.analyses;
+    const paths = designPaths(serviceDirectory(options.service));
+    const existing = yield* readIfPresent(workspace, paths.design);
+    if (existing !== undefined) {
+        const file = yield* parseDesignFile(existing).pipe(Effect.result);
+        if (file._tag === "Failure")
+            return { kind: "failed", detail: file.failure.message };
+        const issues = checkDesign(file.success.design, { catalog, operations, analyses });
+        yield* workspace.write(paths.design, renderDesignFile(file.success.design, issues, file.success.approved ? "approved" : "proposed"));
+        const errors = blockingIssues(issues).length;
+        return {
+            kind: "checked",
+            approved: file.success.approved,
+            errors,
+            warnings: issues.length - errors
+        };
+    }
+    if ("off" in options.reasoning)
+        return { kind: "skipped", reason: options.reasoning.off };
+    if (options.evidence.exchanges === 0) {
+        return { kind: "skipped", reason: "no exchanges yet: the design needs evidence" };
+    }
+    const reasoning = options.reasoning;
+    const base = {
+        catalog,
+        operations,
+        mapping: mapService(catalog),
+        analyses,
+        style: options.style
+    };
+    const drafted = yield* proposeDesign(reasoning, base).pipe(Effect.result);
+    if (drafted._tag === "Failure") {
+        return { kind: "failed", detail: `drafting failed: ${drafted.failure.message}` };
+    }
+    let design = drafted.success;
+    let issues = checkDesign(design, { catalog, operations, analyses });
+    let kind = "drafted";
+    if (blockingIssues(issues).length > 0) {
+        const revised = yield* reviseDesign(reasoning, { ...base, current: design, issues }).pipe(Effect.result);
+        if (revised._tag === "Success") {
+            design = revised.success;
+            issues = checkDesign(design, { catalog, operations, analyses });
+            kind = "revised";
+        }
+    }
+    yield* workspace.write(paths.design, renderDesignFile(design, issues, "proposed"));
+    const errors = blockingIssues(issues).length;
+    return { kind, approved: false, errors, warnings: issues.length - errors };
+});
+// ---------------------------------------------------------------------------
+// Report
+const outcomeText = (outcome) => outcome.kind === "called"
+    ? `called: ${outcome.detail}${outcome.findings === 0 ? "" : `, ${outcome.findings} schema findings`}`
+    : `${outcome.kind}: ${outcome.detail}`;
+const cell = (text) => text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+export const renderExploreReport = (options) => {
+    const { service, catalog, result, design } = options;
+    const paths = servicePaths(service);
+    const lines = [
+        `# Explore: ${service}`,
+        "",
+        "Regenerated by every `soap-explore` run. Every value in the files it points at is masked.",
+        "",
+        `- operations: ${catalog.operations.length}, open questions: ${catalog.openQuestions.length} (see catalog.md)`,
+        `- environment: ${options.profile?.environment ?? "none (no auth.json)"}`,
+        `- operations.md: ${options.operations === undefined ? "missing" : options.operations.confirmed ? "confirmed" : "proposed"}`,
+        `- exchanges recorded: ${options.evidence.exchanges}`,
+        "",
+        "## Operations",
+        "",
+        "| Operation | Class | Probe | Request | Result |",
+        "| --- | --- | --- | --- | --- |"
+    ];
+    for (const report of result.operations) {
+        const request = `samples/${report.operation}/${exploreRequestName} (${report.request})`;
+        lines.push(`| ${cell(report.operation)} | ${report.listed}${options.operations?.confirmed === true ? "" : " (proposed)"} | ${report.decision.probe ? `yes, ${report.decision.basis ?? ""}` : "no"} | ${cell(request)} | ${cell(report.decision.probe ? outcomeText(report.outcome) : report.outcome.kind === "recorded" ? outcomeText(report.outcome) : `not called: ${report.decision.reason}`)} |`);
+    }
+    const chained = result.operations.filter((report) => report.chained.length > 0);
+    if (chained.length > 0) {
+        lines.push("", "## Chained values", "");
+        for (const report of chained) {
+            lines.push(`- ${report.operation} ← ${report.chained.map((link) => `${link.producer} (${link.fields.join(", ")})`).join("; ")}`);
+        }
+    }
+    lines.push("", "## Design", "");
+    switch (design.kind) {
+        case "skipped":
+            lines.push(`Not drafted: ${design.reason}.`);
+            break;
+        case "failed":
+            lines.push(`Not drafted: ${design.detail}`);
+            break;
+        default:
+            lines.push(`design/api-design.md ${design.kind}: ${design.approved ? "approved" : "proposed"}, ${design.errors} errors, ${design.warnings} warnings.`);
+    }
+    const next = [];
+    if (options.profile === undefined) {
+        next.push(`Write \`${paths.auth}\` to enable calls, at least \`{"environment": "test"}\` (dev, test, or uat; add "endpoint" when the WSDL names another environment, and auth by env:/file: reference). Then rerun soap-explore.`);
+    }
+    if (options.operations !== undefined && !options.operations.confirmed) {
+        next.push(`Review the classes in \`${paths.operations}\` and set \`Status: confirmed\`; then rerun soap-explore to probe every read operation.`);
+    }
+    for (const report of result.operations) {
+        if (report.outcome.kind === "failed") {
+            next.push(`${report.operation}: fix \`samples/${report.operation}/${exploreRequestName}.request.yaml\` (delete its first line to keep your edits), then \`soap-sample "call ${report.operation}/${exploreRequestName}"\`.`);
+        }
+    }
+    const mutating = result.operations
+        .filter((report) => report.listed === "mutating" && report.outcome.kind === "not-called")
+        .map((report) => report.operation);
+    if (options.profile !== undefined && mutating.length > 0) {
+        next.push(`Mutating operations are never probed (${mutating.join(", ")}): edit a request, then \`soap-sample -- --allow-mutating <operation> "call <operation>/${exploreRequestName}"\` when a test call is acceptable.`);
+    }
+    if (options.evidence.exchanges > 0) {
+        next.push('More evidence per operation (empty result, business fault, paging): `soap-sample "propose <operation>"`, then `soap-sample "call <operation>"`, then rerun soap-explore.');
+    }
+    if (design.kind === "skipped" || design.kind === "failed") {
+        if (options.evidence.exchanges > 0)
+            next.push('Draft the design: `soap-design "design"`.');
+    }
+    else if (!design.approved) {
+        next.push('Review `design/api-design.md`, run `soap-design "check"` until it has no errors, set `Status: approved`, then `soap-design "openapi"` and `soap-epic`.');
+    }
+    else if (design.errors === 0) {
+        next.push('The design is approved: `soap-design "openapi"`, then `soap-epic -- --target <ace-repo> plan`.');
+    }
+    lines.push("", "## Next", "", ...next.map((line) => `- ${line}`), "");
+    return lines.join("\n");
+};

package/kits/soap-ace/flows/soap-explore.js

@@ -0,0 +1,190 @@
+// One pass from a WSDL to a design draft: discover, a request for every operation, a read-only probe with values chained between calls, analyses, the 1:1 mapping, and a drafted REST design; stops only where a person decides.
+//
+// The task text is the WSDL location (path or http(s) URL), as for
+// soap-discover; without one it continues from the discovered service:
+//
+//   llm4ts run soap-explore --repo ~/work/conti-api ./wsdl/DemoBank.wsdl
+//   llm4ts run soap-explore --repo .                  # rerun: continue where it stopped
+//   llm4ts run soap-explore --repo . -- --refresh     # call the probed operations again
+//
+// Steps, each keeping what already exists (so a rerun continues):
+//
+//   1. discover     catalog.json/.md; operations.md with proposed classes
+//   2. requests     samples/<op>/happy-path.request.yaml for every operation
+//   3. probe        calls read operations only, producers first; values a
+//                   response returns seed the next request (live in memory,
+//                   masked on disk). Before operations.md is confirmed an
+//                   operation is probed only in dev/test when the name
+//                   heuristic and the judgment seat (LLM4TS_JUDGMENT_PROVIDER)
+//                   both say read. Mutating operations are never called.
+//   4. evidence     analysis/<op>.md, design/mapping.json/.md
+//   5. design       the reasoning seat (LLM4TS_REASONER, default claude)
+//                   drafts design/api-design.md, check, one revise round;
+//                   an existing design is only checked. --no-design skips.
+//   6. report       explore.md: per operation what happened, and the next
+//                   command for every gap
+//
+// Calls need auth.json (at least {"environment": "test"}); explore never
+// writes it. Approval stays human: operations.md `Status: confirmed`,
+// api-design.md `Status: approved`. LLM4TS_SOAP_SERVICE names the service
+// (and the auth.json used to fetch a URL); LLM4TS_SOAP_STUB=<dir> answers
+// calls from <dir>/<operation>.xml instead of the network.
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Effect from "effect/Effect";
+import { FlowAborted, Info, makeNodeWorkspace, mock, resolveFlowInput, runFlowMain, runNode, ScriptUsage } from "@llm4ts/runner";
+import { coderFor, judgmentConnectorFromEnvironment } from "@llm4ts/runner/Connectors";
+import { nodeSecretSource, resolveSide } from "./lib/soap/Auth.js";
+import { heuristicClass, judgeClass } from "./lib/soap/Classification.js";
+import { discoverService, loadAuthProfile, loadCatalog, loadOperationsFile } from "./lib/soap/Discover.js";
+import { designStep, explorePaths, exploreService, renderExploreReport, writeEvidence } from "./lib/soap/Explore.js";
+import { makeDirectoryStubTransport } from "./lib/soap/Stub.js";
+import { makeNodeSoapTransport, makeTransportDocumentLoader } from "./lib/soap/Transport.js";
+import { DocumentLoader } from "./lib/soap/Wsdl.js";
+const usage = 'usage: soap-explore [--refresh] [--no-design] "<wsdl path or URL>"';
+const isUrl = (location) => /^https?:\/\//i.test(location);
+const parseExploreFlags = (argv) => Effect.gen(function* () {
+    let refresh = false;
+    let design = true;
+    const rest = [];
+    for (const argument of argv) {
+        if (argument === "--refresh")
+            refresh = true;
+        else if (argument === "--no-design")
+            design = false;
+        else if (argument.startsWith("--refresh=") || argument.startsWith("--no-design="))
+            return yield* ScriptUsage.make({ message: `${argument} takes no value\n${usage}` });
+        else
+            rest.push(argument);
+    }
+    return { refresh, design, rest };
+});
+const styleGuide = () => Effect.tryPromise({
+    try: () => readFile(fileURLToPath(new URL("../packs/ace12-rest/api-style.md", import.meta.url)), "utf8"),
+    catch: () => FlowAborted.make({ message: "cannot read the kit's packs/ace12-rest/api-style.md" })
+});
+const program = Effect.gen(function* () {
+    const flags = yield* parseExploreFlags(process.argv.slice(2));
+    const input = yield* resolveFlowInput("", flags.rest);
+    const raw = input.prompt.trim();
+    const location = raw === "" ? undefined : isUrl(raw) || isAbsolute(raw) ? raw : resolve(input.workspace, raw);
+    const environment = process.env;
+    const requested = environment.LLM4TS_SOAP_SERVICE?.trim() || undefined;
+    const judgment = yield* judgmentConnectorFromEnvironment();
+    const reasonerName = (environment.LLM4TS_REASONER ?? "claude").trim() || "claude";
+    const reasoner = flags.design ? coderFor(reasonerName) : undefined;
+    if (flags.design && reasoner === undefined) {
+        return yield* ScriptUsage.make({ message: `unknown LLM4TS_REASONER '${reasonerName}'` });
+    }
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder: mock,
+        ...(reasoner === undefined ? {} : { reasoning: reasoner }),
+        ...(judgment === undefined ? {} : { judgment }),
+        environment
+    }, (context) => Effect.gen(function* () {
+        const say = (message) => context.events.publish(Info.make({ message }));
+        const workspace = yield* makeNodeWorkspace(input.workDir);
+        const seat = judgment === undefined ? undefined : context.judgment;
+        // 1. discover (or continue from the discovered service)
+        let service;
+        let catalog;
+        let judged;
+        if (location !== undefined) {
+            const fetchProfile = requested === undefined ? undefined : yield* loadAuthProfile(workspace, requested);
+            const fetchSide = yield* resolveSide(nodeSecretSource(environment), fetchProfile?.fetch);
+            const discovered = yield* discoverService({
+                workspace,
+                location,
+                ...(requested === undefined ? {} : { service: requested }),
+                ...(seat === undefined ? {} : { judgment: seat })
+            }).pipe(Effect.provideService(DocumentLoader, makeTransportDocumentLoader(makeNodeSoapTransport(), fetchSide)));
+            service = discovered.service;
+            catalog = discovered.catalog;
+            // Classes judged at discovery are reused; otherwise judged below.
+            if (discovered.proposals !== undefined && seat !== undefined) {
+                judged = new Map(discovered.proposals.map((proposal) => [proposal.operation, proposal.judged]));
+            }
+            yield* say(`discovered ${service}: ${catalog.operations.length} operations, ${catalog.openQuestions.length} open questions`);
+        }
+        else {
+            const services = (yield* workspace.discover(".llm4ts/soap/*/catalog.json")).map((path) => path.split("/")[2] ?? "");
+            const picked = requested ?? (services.length === 1 ? services[0] : undefined);
+            if (picked === undefined) {
+                return yield* FlowAborted.make({
+                    message: services.length === 0
+                        ? `nothing discovered here; give the WSDL\n${usage}`
+                        : `several services (${services.join(", ")}); set LLM4TS_SOAP_SERVICE`
+                });
+            }
+            service = picked;
+            catalog = yield* loadCatalog(workspace, service);
+            yield* say(`continuing ${service}: ${catalog.operations.length} operations`);
+        }
+        const profile = yield* loadAuthProfile(workspace, service);
+        const operations = yield* loadOperationsFile(workspace, service);
+        // Provisional probing asks the judgment only where the listed class
+        // and the heuristic already say read.
+        if (seat !== undefined && judged === undefined && operations?.confirmed !== true) {
+            const candidates = catalog.operations.filter((operation) => operations?.classes.get(operation.name) === "read" &&
+                heuristicClass(operation.name).class === "read");
+            judged = new Map(yield* Effect.forEach(candidates, (operation) => Effect.map(judgeClass(seat, catalog, operation), (answer) => [operation.name, answer])));
+        }
+        // 2-3. requests and the probe
+        const stub = environment.LLM4TS_SOAP_STUB?.trim();
+        const transport = stub === undefined || stub === ""
+            ? makeNodeSoapTransport()
+            : makeDirectoryStubTransport(resolve(input.workspace, stub), catalog);
+        if (stub !== undefined && stub !== "")
+            yield* say(`LLM4TS_SOAP_STUB: answering from ${stub}, not the network`);
+        const result = yield* exploreService({
+            workspace,
+            catalog,
+            service,
+            profile,
+            operations,
+            judged,
+            secrets: nodeSecretSource(environment),
+            transport,
+            refresh: flags.refresh,
+            progress: (line) => say(`  ${line}`)
+        });
+        const probed = result.decisions.filter((decision) => decision.probe).length;
+        yield* say(`probe: ${probed} of ${catalog.operations.length} operations callable now${profile === undefined ? " (no auth.json)" : ""}`);
+        // 4. evidence
+        const evidence = yield* writeEvidence(workspace, catalog, service);
+        // 5. design
+        const design = yield* designStep({
+            workspace,
+            catalog,
+            service,
+            operations,
+            evidence,
+            reasoning: flags.design ? context.reasoning : { off: "--no-design" },
+            style: yield* styleGuide()
+        });
+        yield* say(design.kind === "skipped" || design.kind === "failed"
+            ? `design: not drafted (${design.kind === "skipped" ? design.reason : design.detail})`
+            : `design: ${design.kind}, ${design.approved ? "approved" : "proposed"}, ${design.errors} errors, ${design.warnings} warnings`);
+        // 6. report
+        const report = renderExploreReport({
+            service,
+            catalog,
+            profile,
+            operations,
+            result,
+            design,
+            evidence
+        });
+        const path = explorePaths(service).report;
+        yield* workspace.write(path, report);
+        const next = report.split("## Next")[1]?.trim().split("\n") ?? [];
+        yield* say(`wrote ${path}; next:`);
+        for (const line of next)
+            yield* say(`  ${line}`);
+    }));
+});
+runFlowMain(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/core": "2.15.0",
-    "@llm4ts/runner": "2.15.0",
-    "@llm4ts/flow": "2.15.0"
+    "@llm4ts/core": "2.16.0",
+    "@llm4ts/flow": "2.16.0",
+    "@llm4ts/runner": "2.16.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"