@llm4ts/shell 2.12.0 → 2.13.0

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

@@ -0,0 +1,204 @@
+// Plan the IBM ACE 12 implementation of an approved REST design: seed the ACE repository with contracts, stubs, and house rules, and write the story plan epic-stories executes.
+//
+// Runs rooted at the repository where soap-discover/sample/design ran; the
+// ACE repository is --target (a git repository, created beforehand):
+//
+//   llm4ts run soap-epic --repo . -- --target ~/work/demo-bank-ace plan
+//   llm4ts run soap-epic --repo . doctor          # is ACE 12 usable on this machine?
+//
+// `plan` requires design/api-design.md approved with no check errors. It
+// writes into the target: contracts/ (the design, OpenAPI 3.1 and the 3.0.3
+// variant ACE imports, the 1:1 mapping, the WSDL and XSDs), test-data/ (the
+// masked exchanges, the stubs' source), docs/ (analysis reports, ESQL
+// pattern cards) — all regenerated each run — and, only when absent, the
+// ace12-rest-api scaffold (README, CONTRIBUTING.md house rules, gate
+// scripts). Then it derives the story plan (skeleton, policies, shared
+// library, stubs, one story per resource, contract check) and saves it at
+// <target>/.llm4ts/epics/<epic-id>/plan.md, where epic-stories reads it; an
+// existing plan is kept (editing it is the re-plan). It prints the exact
+// epic-stories command: gates via scripts/ace-gates.sh, no worktree setup,
+// concurrency 2, branches only. LLM4TS_ACE_API names the API project
+// (default from the service), LLM4TS_SOAP_SERVICE picks the service.
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Effect from "effect/Effect";
+import { makeStoryPlanStore } from "@llm4ts/flow/StoryPlan";
+import { FlowAborted, Info, makeNodeWorkspace, mock, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runFlowMain, runNode, ScriptUsage } from "@llm4ts/runner";
+import { analysisPaths, writeAnalyses } from "./lib/soap/Analysis.js";
+import { blockingIssues, checkDesign, designPaths, parseDesignFile } from "./lib/soap/Design.js";
+import { loadCatalog, loadOperationsFile, readIfPresent, serviceDirectory } from "./lib/soap/Discover.js";
+import { apiNameFor, epicSentence, planViolations, seedFiles, storyPlanFor, writeSeed } from "./lib/soap/Epic.js";
+import { readExchanges } from "./lib/soap/Samples.js";
+import { decodeXml } from "./lib/soap/Xml.js";
+const usage = 'usage: soap-epic [--target <ace-repo>] "plan | doctor"';
+const kitRoot = fileURLToPath(new URL("..", import.meta.url));
+const filesUnder = (root) => Effect.promise(async () => {
+    const found = [];
+    const walk = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const full = join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else
+                found.push({ path: relative(root, full), contents: await readFile(full, "utf8") });
+        }
+    };
+    if (existsSync(root))
+        await walk(root);
+    return found;
+});
+const parseEpicFlags = (argv) => Effect.gen(function* () {
+    let target;
+    const rest = [];
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index] ?? "";
+        if (argument === "--target" || argument.startsWith("--target=")) {
+            target = argument.includes("=") ? argument.slice("--target=".length) : argv[++index];
+            if (target === undefined || target === "")
+                return yield* ScriptUsage.make({ message: `--target needs a path\n${usage}` });
+        }
+        else
+            rest.push(argument);
+    }
+    return { target, rest };
+});
+const program = Effect.gen(function* () {
+    const flags = yield* parseEpicFlags(process.argv.slice(2));
+    const input = yield* resolveFlowInput("plan", flags.rest);
+    const [command = "plan"] = input.prompt.trim().split(/\s+/);
+    const environment = process.env;
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder: mock,
+        environment
+    }, (context) => Effect.gen(function* () {
+        const say = (message) => context.events.publish(Info.make({ message }));
+        if (command === "doctor") {
+            const profile = environment.MQSI_PROFILE ??
+                join(environment.ACE_HOME ?? "/opt/ibm/ace-12", "server", "bin", "mqsiprofile");
+            yield* say(`mqsiprofile: ${existsSync(profile) ? "found" : "missing"} at ${profile} (MQSI_PROFILE or ACE_HOME)`);
+            if (!existsSync(profile)) {
+                return yield* FlowAborted.make({
+                    message: "ACE 12 is not installed here, or MQSI_PROFILE/ACE_HOME do not point at it; the container gate (scripts/ace-gates-container.sh with ACE_IMAGE) is the alternative"
+                });
+            }
+            // Only presence and version: the gates themselves prove the rest.
+            const checks = [
+                ["ACE version", "mqsiservice -v"],
+                ["ibmint", "command -v ibmint"],
+                ["IntegrationServer", "command -v IntegrationServer"],
+                ["mqsicreateworkdir", "command -v mqsicreateworkdir"]
+            ];
+            for (const [label, check] of checks) {
+                const result = yield* nodeProcessExecutor
+                    .run(["bash", "-c", `set +u; . "${profile}" >/dev/null 2>&1; ${check}`], input.workDir, {})
+                    .pipe(Effect.result);
+                const line = result._tag === "Success" && result.success.exitCode === 0
+                    ? `ok (${result.success.stdout.find((entry) => entry.trim() !== "")?.trim() ?? ""})`
+                    : "not found";
+                yield* say(`${label}: ${line}`);
+            }
+            return;
+        }
+        if (command !== "plan")
+            return yield* FlowAborted.make({ message: `unknown command ${command}\n${usage}` });
+        if (flags.target === undefined)
+            return yield* FlowAborted.make({ message: `plan needs --target <ace-repo>\n${usage}` });
+        const targetRoot = resolve(input.workspace, flags.target);
+        if (!existsSync(targetRoot))
+            return yield* FlowAborted.make({
+                message: `${targetRoot} does not exist; create the ACE repository (git init) first`
+            });
+        if (!existsSync(join(targetRoot, ".git")))
+            yield* say(`⚠ ${targetRoot} is not a git repository; epic-stories needs one with at least one commit`);
+        const workspace = yield* makeNodeWorkspace(input.workDir);
+        const requested = environment.LLM4TS_SOAP_SERVICE?.trim();
+        const services = (yield* workspace.discover(".llm4ts/soap/*/catalog.json")).map((path) => path.split("/")[2] ?? "");
+        const service = requested !== undefined && requested !== ""
+            ? requested
+            : services.length === 1
+                ? services[0]
+                : undefined;
+        if (service === undefined) {
+            return yield* FlowAborted.make({
+                message: services.length === 0
+                    ? "no discovered service here; run soap-discover first"
+                    : `several services (${services.join(", ")}); set LLM4TS_SOAP_SERVICE`
+            });
+        }
+        const catalog = yield* loadCatalog(workspace, service);
+        const operations = yield* loadOperationsFile(workspace, service);
+        const paths = designPaths(serviceDirectory(service));
+        const text = yield* readIfPresent(workspace, paths.design);
+        if (text === undefined)
+            return yield* FlowAborted.make({ message: `no ${paths.design}; run soap-design first` });
+        const file = yield* parseDesignFile(text);
+        const analyses = yield* writeAnalyses(workspace, catalog, service);
+        const errors = blockingIssues(checkDesign(file.design, { catalog, operations, analyses }));
+        if (!file.approved || errors.length > 0) {
+            return yield* FlowAborted.make({
+                message: `${paths.design} must be approved with no check errors (${file.approved ? `${errors.length} errors` : "not approved"}); run soap-design "check"`
+            });
+        }
+        const api = environment.LLM4TS_ACE_API?.trim() || apiNameFor(service);
+        const soapRoot = catalog.documents[0] === undefined ? undefined : dirname(catalog.documents[0]);
+        // Schemas may be declared in ISO-8859-1: decode by their declaration and
+        // re-emit as UTF-8 so the ACE toolkit and git see one encoding.
+        const soapDocuments = yield* Effect.forEach(catalog.documents.filter((document) => !/^https?:/i.test(document)), (document) => Effect.gen(function* () {
+            const bytes = yield* Effect.promise(() => readFile(document));
+            const text = yield* decodeXml(new Uint8Array(bytes), document);
+            return {
+                path: relative(soapRoot ?? dirname(document), document),
+                contents: text.replace(/^(<\?xml[^>]*?encoding\s*=\s*["'])[^"']+(["'])/, "$1UTF-8$2")
+            };
+        }));
+        if (soapDocuments.length < catalog.documents.length) {
+            yield* say("⚠ the WSDL was read from a URL: download it and its schemas into contracts/soap/ of the ACE repository");
+        }
+        const analysisMarkdown = yield* Effect.forEach(catalog.operations, (operation) => Effect.map(workspace.read(analysisPaths(service, operation.name).markdown), (markdown) => ({ operation: operation.name, markdown })));
+        const files = seedFiles({
+            design: file.design,
+            catalog,
+            service,
+            api,
+            scaffold: yield* filesUnder(join(kitRoot, "scaffolds", "ace12-rest-api")),
+            patterns: yield* filesUnder(join(kitRoot, "patterns")),
+            soapDocuments,
+            analyses: analysisMarkdown,
+            exchanges: yield* readExchanges(workspace, service)
+        });
+        // The plan is derived and checked before anything touches the target.
+        const plan = storyPlanFor({ design: file.design, service, api, analyses });
+        const violations = planViolations(plan);
+        if (violations.length > 0)
+            return yield* FlowAborted.make({
+                message: `derived story plan is invalid:\n${violations.join("\n")}`
+            });
+        const target = yield* makeNodeWorkspace(targetRoot);
+        const seeded = yield* writeSeed(target, files);
+        yield* say(`seeded ${targetRoot}: ${seeded.written} files written, ${seeded.kept} team-owned files kept`);
+        const planPath = join(targetRoot, ".llm4ts", "epics", plan.epicId, "plan.md");
+        const store = makeStoryPlanStore(nodePlainFileStore);
+        const existing = yield* store.load(planPath);
+        if (existing === undefined) {
+            yield* store.save(planPath, plan);
+            yield* say(`story plan: ${plan.stories.length} stories at ${planPath}`);
+        }
+        else {
+            yield* say(`kept the existing story plan at ${planPath} (${existing.stories.length} stories); delete it to re-derive`);
+        }
+        for (const story of plan.stories) {
+            yield* say(`  ${story.id}${story.dependsOn.length === 0 ? "" : ` (after ${story.dependsOn.join(", ")})`}: owns ${story.owned.join(", ")}`);
+        }
+        yield* say([
+            "next: review the plan, commit the seed in the ACE repository, then run",
+            `  LLM4TS_GATES="bash scripts/ace-gates.sh build;bash scripts/ace-gates.sh test" LLM4TS_WORKTREE_SETUP= \\`,
+            `    llm4ts run epic-stories --repo ${targetRoot} -- --concurrency 2 ${JSON.stringify(epicSentence(file.design, api, service))}`
+        ].join("\n"));
+    }));
+});
+runFlowMain(program);

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

@@ -0,0 +1,265 @@
+// Author, call, and import SOAP samples: YAML request files from the catalog, masked recorded exchanges, SoapUI import, LLM-proposed scenario sets.
+//
+// Runs after soap-discover, rooted at the same repository. The task text is
+// a command:
+//
+//   llm4ts run soap-sample --repo . "list"                    requests and exchanges per operation
+//   llm4ts run soap-sample --repo . "init cercaMovimenti"     a commented skeleton (happy-path)
+//   llm4ts run soap-sample --repo . "init cercaMovimenti fine-mese"
+//   llm4ts run soap-sample --repo . "propose cercaMovimenti"  scenario set from the reasoning seat
+//   llm4ts run soap-sample --repo . "import ./DemoBank-soapui-project.xml"
+//   llm4ts run soap-sample --repo . "call cercaMovimenti/happy-path"
+//   llm4ts run soap-sample --repo . "call cercaMovimenti"     every request of the operation
+//   llm4ts run soap-sample --repo . -- --allow-mutating revocaBonifico "call revocaBonifico/gia-eseguito"
+//
+// Requests live in .llm4ts/soap/<service>/samples/<operation>/<name>.request.yaml
+// (or .request.xml). A call validates the request (an invalid one is never
+// sent), checks the confirmed class in operations.md and the environment's
+// mutating policy, sends it with auth.json's call side (Basic/Bearer, mTLS,
+// WS-Security), and records a masked, auth-stripped exchange beside it.
+// Flags: --allow-mutating <operation> (exactly one), --keep-raw (unmasked
+// response under the gitignored raw/). LLM4TS_SOAP_SERVICE picks the service
+// when several were discovered; LLM4TS_SOAP_STUB=<dir> answers calls from
+// <dir>/<operation>.xml instead of the network (rehearsals); LLM4TS_REASONER
+// picks the seat that proposes scenarios (default claude).
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import * as Effect from "effect/Effect";
+import { FlowAborted, Info, makeNodeWorkspace, mock, resolveFlowInput, runFlowMain, runNode, ScriptUsage } from "@llm4ts/runner";
+import { coderFor } from "@llm4ts/runner/Connectors";
+import { terminalInteraction } from "@llm4ts/runner/TerminalInteraction";
+import { nodeSecretSource } from "./lib/soap/Auth.js";
+import { callOperation } from "./lib/soap/Call.js";
+import { operationByName } from "./lib/soap/Catalog.js";
+import { effectiveClass } from "./lib/soap/Classification.js";
+import { loadAuthProfile, loadCatalog, loadOperationsFile, readIfPresent } from "./lib/soap/Discover.js";
+import { isSampleName, listRequests, loadMaskingKey, loadMaskingOverrides, readExchanges, renderRequestFile, samplePaths, seedsForService } from "./lib/soap/Samples.js";
+import { proposeScenarios } from "./lib/soap/Scenarios.js";
+import { importSoapUiProject } from "./lib/soap/SoapUiImport.js";
+import { makeDirectoryStubTransport } from "./lib/soap/Stub.js";
+import { makeNodeSoapTransport } from "./lib/soap/Transport.js";
+const usage = [
+    'usage: soap-sample [--allow-mutating <operation>] [--keep-raw] "<command>"',
+    "  list | init <operation> [name] | propose <operation> | import <soapui.xml>",
+    "  call <operation>[/<name>] | call all"
+].join("\n");
+const parseSampleFlags = (argv) => Effect.gen(function* () {
+    let allowMutating;
+    let keepRaw = false;
+    const rest = [];
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index] ?? "";
+        if (argument === "--keep-raw")
+            keepRaw = true;
+        else if (argument === "--allow-mutating" || argument.startsWith("--allow-mutating=")) {
+            const value = argument.includes("=")
+                ? argument.slice("--allow-mutating=".length)
+                : argv[++index];
+            if (value === undefined || value.trim() === "") {
+                return yield* ScriptUsage.make({
+                    message: `--allow-mutating needs an operation name\n${usage}`
+                });
+            }
+            allowMutating = value.trim();
+        }
+        else
+            rest.push(argument);
+    }
+    return { allowMutating, keepRaw, rest };
+});
+/** The service directory: LLM4TS_SOAP_SERVICE, or the only one discovered. */
+const pickService = (workspace, requested) => Effect.gen(function* () {
+    if (requested !== undefined && requested !== "")
+        return requested;
+    const catalogs = yield* workspace.discover(".llm4ts/soap/*/catalog.json");
+    const services = catalogs.map((path) => path.split("/")[2] ?? "");
+    if (services.length === 1)
+        return services[0] ?? "";
+    return yield* FlowAborted.make({
+        message: services.length === 0
+            ? "no discovered service here; run soap-discover first"
+            : `several services (${services.join(", ")}); set LLM4TS_SOAP_SERVICE`
+    });
+});
+const requireOperation = (catalog, name) => name !== undefined && operationByName(catalog, name) !== undefined
+    ? Effect.succeed(name)
+    : FlowAborted.make({
+        message: `unknown operation ${name ?? "(none)"}; one of: ${catalog.operations.map((operation) => operation.name).join(", ")}`
+    });
+const program = Effect.gen(function* () {
+    const flags = yield* parseSampleFlags(process.argv.slice(2));
+    const input = yield* resolveFlowInput("list", flags.rest);
+    const [command = "list", ...args] = input.prompt.trim().split(/\s+/);
+    const environment = process.env;
+    const reasoner = command === "propose"
+        ? coderFor((environment.LLM4TS_REASONER ?? "claude").trim() || "claude")
+        : undefined;
+    if (command === "propose" && reasoner === undefined) {
+        return yield* ScriptUsage.make({
+            message: `unknown LLM4TS_REASONER '${environment.LLM4TS_REASONER ?? ""}'`
+        });
+    }
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder: mock,
+        ...(reasoner === undefined ? {} : { reasoning: reasoner }),
+        environment
+    }, (context) => Effect.gen(function* () {
+        const say = (message) => context.events.publish(Info.make({ message }));
+        const workspace = yield* makeNodeWorkspace(input.workDir);
+        const service = yield* pickService(workspace, environment.LLM4TS_SOAP_SERVICE?.trim());
+        const catalog = yield* loadCatalog(workspace, service);
+        const operations = yield* loadOperationsFile(workspace, service);
+        switch (command) {
+            case "list": {
+                const exchanges = yield* readExchanges(workspace, service);
+                for (const operation of catalog.operations) {
+                    const requests = yield* listRequests(workspace, service, operation.name);
+                    const recorded = exchanges.filter((exchange) => exchange.operation === operation.name);
+                    const faults = recorded.filter((exchange) => exchange.fault !== undefined).length;
+                    const breaking = recorded.filter((exchange) => exchange.responseIssues.length > 0).length;
+                    yield* say(`${operation.name} [${effectiveClass(operations, operation.name)}]: ${requests.length} requests${requests.length === 0 ? "" : ` (${requests.join(", ")})`}, ${recorded.length} exchanges, ${faults} faults, ${breaking} schema findings`);
+                }
+                if (operations?.confirmed !== true) {
+                    yield* say(`operations.md is not confirmed: nothing can be called yet`);
+                }
+                return;
+            }
+            case "init": {
+                const operation = yield* requireOperation(catalog, args[0]);
+                const name = args[1] ?? "happy-path";
+                if (!isSampleName(name)) {
+                    return yield* FlowAborted.make({ message: `request names are kebab-case: ${name}` });
+                }
+                const paths = samplePaths(service, operation, name);
+                if ((yield* readIfPresent(workspace, paths.yaml)) !== undefined ||
+                    (yield* readIfPresent(workspace, paths.xml)) !== undefined) {
+                    return yield* FlowAborted.make({
+                        message: `${operation}/${name} exists; edit it or pick another name`
+                    });
+                }
+                const seeds = yield* seedsForService(workspace, catalog, service);
+                yield* workspace.write(paths.yaml, renderRequestFile({ catalog, operation, purpose: name.replace(/-/g, " "), seeds }));
+                yield* say(`wrote ${paths.yaml}; edit it, then: soap-sample "call ${operation}/${name}"`);
+                return;
+            }
+            case "propose": {
+                const operation = yield* requireOperation(catalog, args[0]);
+                const seeds = yield* seedsForService(workspace, catalog, service);
+                const written = yield* proposeScenarios({
+                    reasoning: context.reasoning,
+                    workspace,
+                    catalog,
+                    service,
+                    operation,
+                    operationClass: effectiveClass(operations, operation),
+                    seeds
+                });
+                for (const scenario of written) {
+                    yield* say(scenario.kept
+                        ? `kept existing ${scenario.path}`
+                        : `wrote ${scenario.path}${scenario.issues.length === 0 ? "" : ` (${scenario.issues.length} problems to fix, listed in the file)`}`);
+                }
+                return;
+            }
+            case "import": {
+                const file = args.join(" ");
+                if (file === "")
+                    return yield* FlowAborted.make({
+                        message: `import needs a SoapUI project path\n${usage}`
+                    });
+                const project = yield* Effect.tryPromise({
+                    try: () => readFile(resolve(input.workspace, file), "utf8"),
+                    catch: () => FlowAborted.make({ message: `cannot read ${file}` })
+                });
+                const key = yield* loadMaskingKey(workspace, service);
+                const overrides = yield* loadMaskingOverrides(workspace, service);
+                const report = yield* importSoapUiProject({
+                    workspace,
+                    catalog,
+                    service,
+                    project,
+                    key,
+                    ...(overrides === undefined ? {} : { overrides })
+                });
+                for (const request of report.requests) {
+                    yield* say(`request ${request.path}${request.issues.length === 0 ? "" : ` (${request.issues.length} problems, listed in the file)`}`);
+                }
+                for (const response of report.responses)
+                    yield* say(`exchange ${response.path}`);
+                for (const line of report.skipped)
+                    yield* say(`skipped: ${line}`);
+                if (report.credentialsIgnored > 0) {
+                    yield* say(`${report.credentialsIgnored} stored credentials in the project were ignored; put references in auth.json instead`);
+                }
+                yield* say(`masked ${report.masking.entries.reduce((sum, entry) => sum + entry.count, 0)} values`);
+                return;
+            }
+            case "call": {
+                const target = args[0] ?? "";
+                const profile = yield* loadAuthProfile(workspace, service);
+                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 targets = [];
+                const operationNames = target === "all"
+                    ? catalog.operations.map((operation) => operation.name)
+                    : [yield* requireOperation(catalog, target.split("/")[0])];
+                for (const operation of operationNames) {
+                    const names = target.includes("/")
+                        ? [target.split("/")[1] ?? ""]
+                        : yield* listRequests(workspace, service, operation);
+                    for (const name of names)
+                        targets.push([operation, name]);
+                }
+                if (targets.length === 0)
+                    return yield* FlowAborted.make({
+                        message: `no requests for ${target}; start with soap-sample "init ${target}"`
+                    });
+                const confirm = (question) => process.stdin.isTTY === true
+                    ? terminalInteraction.ask(question).pipe(Effect.map((answer) => /^(y|yes|s|si|sì)$/i.test(answer.trim())), Effect.orElseSucceed(() => false))
+                    : Effect.succeed(false);
+                let failures = 0;
+                for (const [operation, name] of targets) {
+                    const outcome = yield* callOperation({
+                        workspace,
+                        catalog,
+                        service,
+                        operation,
+                        name,
+                        profile,
+                        operations,
+                        secrets: nodeSecretSource(environment),
+                        transport,
+                        allowMutating: flags.allowMutating,
+                        confirm,
+                        keepRaw: flags.keepRaw
+                    }).pipe(Effect.result);
+                    if (outcome._tag === "Failure") {
+                        failures++;
+                        yield* say(`${operation}/${name}: ${outcome.failure.message}`);
+                        continue;
+                    }
+                    const { exchange } = outcome.success;
+                    const status = exchange.fault !== undefined
+                        ? `fault ${exchange.fault.code} ${exchange.fault.reason}`
+                        : `HTTP ${exchange.response?.status ?? "?"}`;
+                    yield* say(`${operation}/${name}: ${status}, ${exchange.response?.elapsedMs ?? 0} ms, ${exchange.responseIssues.length} schema findings, ${exchange.masking.entries.reduce((sum, entry) => sum + entry.count, 0)} values masked → ${outcome.success.path}`);
+                }
+                if (failures > 0)
+                    return yield* FlowAborted.make({
+                        message: `${failures} of ${targets.length} calls did not complete`
+                    });
+                return;
+            }
+            default:
+                return yield* FlowAborted.make({ message: `unknown command ${command}\n${usage}` });
+        }
+    }));
+});
+runFlowMain(program);

package/kits/soap-ace/packs/ace12-rest/api-style.md

@@ -0,0 +1,63 @@
+# REST API style guide (soap-ace default)
+
+The design step treats every rule here as a hard constraint and the design
+judge scores against it. A bank-specific guide replaces this file by
+shipping a project-tier copy of the kit
+(`.llm4ts/kits/soap-ace/packs/ace12-rest/api-style.md`).
+
+## Resources and paths
+
+- Resources are plural nouns in kebab-case: `/accounts`, `/credit-transfers`.
+- Identifiers are path segments: `/accounts/{accountId}`. An IBAN used as an
+  identifier is still an opaque path parameter.
+- Sub-collections only for true containment:
+  `/accounts/{accountId}/movements`.
+- Actions that are not CRUD are sub-resources named by the resulting state,
+  POSTed: `/credit-transfers/{id}/confirmation`, `/credit-transfers/{id}/revocation`.
+- Versioning in the path: `/v1/...`. Breaking changes need a new version.
+
+## Methods
+
+- `GET` only for operations classified `read`; it never changes state.
+- `POST` creates or triggers; `PUT` replaces; `PATCH` (JSON Merge Patch) for
+  partial updates; `DELETE` removes.
+- Creating `POST`s return `201` with a `Location` header.
+
+## Payloads
+
+- JSON with camelCase property names in English; SOAP names are mapped, not
+  carried over (`dataContabile` → `bookingDate`).
+- No wrapper objects that only mirror a SOAP element; no `esito` envelope in
+  successful responses: success is the HTTP status.
+- Dates are ISO 8601 (`2026-09-25`), timestamps ISO 8601 with offset.
+- Amounts are `{ "amount": "1234.56", "currency": "EUR" }`: the amount is a
+  decimal string, the currency ISO 4217.
+- Enumerations are UPPER_SNAKE_CASE strings; values are mapped to English
+  when the meaning is clear, otherwise kept and documented.
+- Absent optional values are omitted, not `null`, unless `null` carries meaning.
+
+## Errors
+
+- Errors are RFC 9457 problem details (`application/problem+json`) with
+  `type`, `title`, `status`, `detail`, and a stable machine-readable `code`.
+- SOAP faults and `esito` KO codes map to statuses by meaning: validation →
+  `400`/`422`, not found → `404`, state conflict → `409`, authorization →
+  `403`, backend unavailable → `503`, anything unmapped → `502`.
+- Backend codes are kept in the problem's `code`, never exposed as the HTTP
+  status or as free text only.
+
+## Collections
+
+- Lists are wrapped: `{ "items": [...], "page": {...} }`.
+- Pagination follows what the SOAP service actually does, as observed in the
+  samples: page-number pagination (`page`, `size`, `totalItems` when known)
+  or cursor pagination (`next` cursor) — never both on one resource.
+- Filters are query parameters named after the response properties they
+  filter (`?status=ACTIVE`, `?bookingDateFrom=...&bookingDateTo=...`).
+
+## Traceability
+
+- Every endpoint names the SOAP operation(s) it is built from, and every
+  property names its XSD path, in the design document.
+- A SOAP operation not exposed is listed as deliberately excluded, with the
+  reason.

package/kits/soap-ace/packs/ace12-rest/pack.md

@@ -0,0 +1,18 @@
+# Pack: ace12-rest
+
+source: soap
+scaffold: ../../scaffolds/ace12-rest-api
+sources: .*\.(wsdl|xsd)
+specs-dir: contracts
+features-dir: ACE_Test/src
+
+## Gates
+
+- build: bash scripts/ace-gates.sh build
+- test: bash scripts/ace-gates.sh test
+
+## Judge
+
+- contract (0..2): Every operation, parameter, property, status, and problem code of the OpenAPI contract is implemented exactly; nothing is added. Score 2 only if the implementation matches the contract completely.
+- mapping (0..2): Every value is built from the x-soap-source the contract names, amounts stay decimal strings, and every x-soap-enum-map entry, including values seen only in the samples, is handled. Score 2 only if no mapping is guessed.
+- errors (0..2): Every esito code and SOAP fault listed in x-problem-codes becomes its problem response, and nothing unmapped leaks backend text. Score 2 only if every error path is implemented and tested.

package/kits/soap-ace/packs/ace12-rest/prompts/implement.md

@@ -0,0 +1,8 @@
+Implement the story in the ACE 12 projects of this repository, following
+CONTRIBUTING.md and the pattern cards in docs/patterns/. The contract in
+contracts/ is fixed: implement it, never change it. Build every request and
+response field from the x-soap-source the contract names and the WSDL in the
+shared library; route every business error and fault through the error
+subflow with the status and code x-problem-codes gives. Add ACE unit tests
+against the recorded stubs for the happy path, every mapped error, and every
+enum value.

package/kits/soap-ace/packs/ace12-rest/reviewers/contract.md

@@ -0,0 +1,5 @@
+Review the change against contracts/openapi-ace.yaml: an operation, field,
+status, or problem code that differs from the contract is a finding; so is a
+value built from anything but its x-soap-source, an enum value missing from
+its CASE, an amount emitted as a number, a hard-coded endpoint or credential,
+or a mapped error without a test.

package/kits/soap-ace/patterns/PAT-ACE-001-esito-to-problem.md

@@ -0,0 +1,8 @@
+---
+match: esito|codice|KO\d\d|problem
+---
+A SOAP response can fail inside HTTP 200: `esito.codice` other than the OK
+code is a business error. Test it before mapping the payload; look the code up
+in the operation's `x-problem-codes` and route to the error subflow with the
+HTTP status, problem `code`, and `title` from the contract. Trap: mapping the
+payload first and checking esito afterwards returns half-filled 200s.

package/kits/soap-ace/patterns/PAT-ACE-002-fault-to-problem.md

@@ -0,0 +1,8 @@
+---
+match: Fault|faultcode|ServizioFault|SOAPRequest
+---
+A SOAP fault arrives on the SOAPRequest node's Failure/Fault terminal, not
+Out. Read `faultcode`, `faultstring`, and the detail element's local name,
+map them through `x-problem-codes`, and answer with the problem status.
+Anything unmapped is `502 backend-error`; never forward faultstring text
+verbatim to the client (it can carry internal data).

package/kits/soap-ace/patterns/PAT-ACE-003-amounts-and-enums.md

@@ -0,0 +1,8 @@
+---
+match: importo|saldo|valore|divisa|amount|enumMap|x-soap-enum-map
+---
+Amounts leave as `{ "amount": "<decimal string>", "currency": "EUR" }`:
+`CAST(value AS CHARACTER)` keeps the digits the backend sent. Enumerations go
+through a CASE built from `x-soap-enum-map`, one WHEN per SOAP value, and an
+ELSE that raises the mapping error. Trap: values seen in the samples but
+missing from the WSDL (the analysis lists them) must be in the CASE too.

package/kits/soap-ace/patterns/PAT-ACE-004-pagination.md

@@ -0,0 +1,7 @@
+---
+match: paginazione|numeroPagina|page|size|ultimaPagina
+---
+Page-number pagination maps query `page`/`size` to the SOAP paging fields,
+defaulting as the contract's `x-derivation` says, and builds `page` from the
+response: `hasNext` from the last-page flag (inverted), `totalItems` only when
+the backend sent it. Clamp `size` to the contract maximum before calling.

package/kits/soap-ace/patterns/PAT-ACE-005-nil-and-absence.md

@@ -0,0 +1,7 @@
+---
+match: nil|nillable|nullable|optional
+---
+Absent SOAP elements are omitted from the JSON; `xsi:nil="true"` becomes
+`null` only for properties the contract marks `nullable`, otherwise the
+property is omitted. Never emit empty strings for absent values: an empty
+string is data. Test both an absent and a nil element per nullable property.