Crafter.Review/implementations/Crafter.Review-Prompt.cpp

// SPDX-License-Identifier: AGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

module Crafter.Review:Prompt_impl;
import :Prompt;
import :Json;
import :Text;
import :Core;
import :Plan;
import :PgWire;
import std;

namespace Crafter::Review::Prompt {
    const std::string_view GenericVocab =
        "Coverage vocabulary: clear (you checked this unit by your charter and found nothing - the basis says what you checked it against: the tree ref, the command run, the steps taken in the application and the evidence file), "
        "defect (a finding with items:[id] exists), immaterial (a note kind=immaterial with items:[id] exists), n/a (the unit carries nothing your charter judges - the basis says why). "
        "For the functional lens \"clear\" means the behaviour of the unit was exercised in the running application and observed as the code intends, never read as plausible; a unit with no reachable behaviour is n/a with the reason, and a behaviour you could not reach for a reason that is not by design is an `unverified` note with n/a, never clear.";

    const std::string_view GenericVocabKernel =
        "Coverage vocabulary for this lens: clear (you checked this unit by your charter and found nothing - the basis says what you checked it against: the source fetched, the tree ref, the units you crossed it with), "
        "defect (a finding with items:[id] exists), immaterial (a note kind=immaterial with items:[id] exists), n/a (the unit carries nothing your charter judges - the basis says why; a paragraph of claims is never n/a). "
        "For the facts lens \"clear\" means every claim in the unit was checked at its source, not read as plausible; for the consistency lens the basis names the unit ids crossed; for the conciseness lens the basis names the class that keeps each sentence.";
    const std::string_view PersonaVocab =
        "Coverage vocabulary for a maintainer or reviewer: would-require (you would ask for this yourself), no-comment, would-object (you would push back - a finding with items:[id] must exist), incomplete (the unit is right but misses what a fix must contain - finding required), not-mine (not your tree, file or decision). "
        "For the recipient persona: can-act, ambiguous (finding required), would-push-back (finding required), already-known, not-mine. basis = the message-id of YOUR OWN mail, or a tree fact (file:line), that grounds the verdict - or the literal string \"no record\"; never a paraphrase of reputation. "
        "A no-comment on a unit that changes your file needs a message where you accepted the same construct; otherwise the basis is \"no record\".";

    const std::string_view WholeFirst =
        "SCOPE - WHOLE PASS, and it gates the block passes of this lens: judge the artifact as an APPROACH - is this the right solution at all, architecturally and at the subsystem level (the alternatives, the maintainers' stated direction, what upstream already has)? "
        "Do not review individual hunks or sentences; per-block passes of this lens run only if you pass. Return `summary` (5-10 sentences: the approach as you judged it and the constraints the block passes must respect). Cover exactly the units listed below (the whole:* slots).";
    const std::string_view WholeAll =
        "SCOPE - WHOLE PASS of the consistency lens, and it gates the block passes: the artifact as a whole - the route it recommends and whether every dependent item carries it through (whole:route), the total set of asks and whether they are legible and free of contradictions (whole:asks), what a reader would expect and does not find (whole:absent), the ledger collision check of your charter, and contradictions between the parts of the artifact. "
        "Per-unit consistency is checked by parallel block passes of this lens that run only if you pass - do not duplicate them. Return `summary` (5-10 sentences the block passes rest on). Cover exactly the units listed below (the whole:* slots).";
    const std::string_view WholePersona =
        "SCOPE - WHOLE PASS as this person, and it gates the block passes: read the whole artifact as they would and write the review they would actually send (predictedReview), the disposition-review notes your charter requires, and cover exactly the units listed below (the whole:* slots). "
        "Return `summary` as a calibration digest for the block passes (this reviewer's pet issues, phrasing and imperatives, found in their own mail - name the message-ids). Return in `notMine` every unit id that is not this person's tree, file or decision - those units get no block pass from this persona; leave it empty for a recipient persona.";

    const std::string_view HintAnchor =
        "This unit fixes the as-of date for every state statement in the artifact. Sweep lore for movement since that date in the threads the artifact cites (the prefetched references give the message-ids; use utilities/lore.py search for newer versions and replies) and report every statement the movement falsifies as a finding; a statement still true is part of your basis.";
    const std::string_view HintRefs =
        "Check that every [n] line resolves (the prefetched index), that the numbering is contiguous and matches the body, and that no entry is unused or orphaned; whether each citation is apt is judged by the unit that cites it.";
    const std::string_view HintOutsideKernel = "Judge the in-tree users and callers of what this patch changes, at the submission base, outside its own diff.";
    const std::string_view HintAbsentKernel = "Judge what a reviewer expects in this patch and does not find: a trailer, a test statement, a Cc, a binding property, an error path.";
    const std::string_view TextBlockHint = "Within this unit, verify its own dated statements against the anchor date and its own [n] citations against the prefetched raw files.";

    const std::string_view WholeFirstRepo =
        "SCOPE - WHOLE PASS, and it gates the block passes of this lens: judge the range as an APPROACH for THIS repository - is this the right solution at all (an existing mechanism in the repository or its platform, the right layer or component, the right commit shape, compatibility with what users already have installed)? "
        "Do not review individual hunks; per-block passes of this lens run only if you pass. Return `summary` (5-10 sentences: the approach as you judged it and the constraints the block passes must respect). Cover exactly the units listed below (the whole:* slots).";

    const std::string_view WholeFunctional =
        "SCOPE - WHOLE PASS, and it gates the block passes of this lens: exercise the range as a USER of the running application named under APPLICATION UNDER TEST. From the code and the commit messages derive every behaviour the range adds, changes or removes and every flow it touches; "
        "reach each one in the browser, act, observe, and compare what you see with what the code says; then exercise one adjacent flow per shared component, store, RPC or function the range touches. A behaviour that does not do what the code intends, a flow the range breaks, or a promised behaviour the application does not deliver is a finding with the steps and the evidence. "
        "Do not judge individual hunks in isolation; the block passes of this lens do that and run only if you pass. Return `summary` (5-10 sentences the block passes rest on: how to reach each touched screen, the login used, what was exercised, what the block passes must not touch or change). Cover exactly the units listed below (the whole:* slots).";

    const std::string_view FunctionalBlockHint =
        "This pass judges ONE hunk in the running application: find the behaviour this hunk changes (what a user does, what the application answers), reach it as a user - the whole pass of this lens says how - exercise it, including the error or empty path the hunk touches, and compare what you observe with what the code says it does. "
        "A hunk whose change has no reachable behaviour of its own (a type, a helper only other hunks make visible, a test, a build script) is n/a with the reason - never clear. "
        "The stack (the application, its database, the account) is yours alone while this pass runs, but it is not reset between passes: earlier passes may have left records in it and later ones will see yours - create only what you need, name it with this unit id, never delete or change what you did not create in this pass, and leave the account as you found it.";

    const std::string_view ShotRules =
        "Take a screenshot (browser_take_screenshot, WITHOUT a filename - the server stores it under this pass's output directory and returns the path; a filename you choose is written into the repository's working tree) of every state a finding or a clear verdict rests on; the returned path is your evidence. browser_snapshot before every action - element refs come from the snapshot and die on navigation. After two failed attempts at the same target, stop and record an `unverified` note saying what blocked you.";

    const std::string_view HintOutside =
        "Judge the in-repository users and callers of what this commit changes, outside its own diff - at the base (`git -C <tree> show <base>:<path>`) and at HEAD.";
    const std::string_view HintAbsent =
        "Judge what a reviewer of this repository expects in this commit and does not find: a commit body at all (a body-less commit has no pK:msg unit), a test, a version or changelog bump, a doc or packaging update, an error path, a migration for existing installs.";
    const std::string_view TextBlockHintRepo =
        "Within this unit, verify every claim against this commit's diff and the repository at HEAD and at the base; a device, field or network claim against the evidence paths INPUTS names, or report it unverifiable.";
    const std::string_view DocBlockHintRepo =
        "This unit is documentation the commit adds or changes: a diff hunk of a documentation file, or one heading-delimited part of it. Judge the lines the commit adds (\"+\"): every claim in them must hold for the repository as THIS commit leaves it "
        "(`git -C <tree> show <sha>:<path>`, the sha on this patch's `From` line) and, where the document at HEAD still carries it, at HEAD too - a later commit of the range may have made it false without updating it; a device, field or network claim against the evidence paths INPUTS names, or report it unverifiable. "
        "Context lines are context and removed lines are not claims, except a context sentence this commit's own change makes false.";

    std::string_view SlotDuty(std::string_view lensFile, std::string_view unitId) {
        if (lensFile == "etiquette.md" && unitId == "whole:asks") {
            return "; for this lens that includes Step 0 and the point map: every point the mail being answered raised - is each answered somewhere, none silently skipped? List them with where each is answered";
        }
        if (lensFile == "conciseness.md" && unitId == "whole:absent") {
            return "; for this lens that includes the growth calibration against the first reviewed version and cross-unit duplication (the same point made in two units)";
        }
        if (lensFile == "process-docs.md" && unitId == "whole:asks") return "; for this lens that includes recipients (get_maintainer), subject and cover mechanics";
        if (lensFile == "minimalism.md" && unitId == "whole:absent") {
            return "; for this lens that includes series-level minimalism: patches or hunks that are unnecessary as a whole, split or merged wrongly, or belong in another series";
        }
        if (lensFile == "facts.md" && unitId == "whole:route") {
            return "; for this lens that means the claims that span units - does every item that depends on the recommended route state the same facts about it";
        }
        if (lensFile != Plan::FactsLens) return {};
        if (unitId == "whole:order") {
            return "; for this lens that means each message describes its own commit alone - nothing a message claims is delivered by a later commit of the range, and no message describes the state a later commit creates";
        }
        if (unitId == "whole:absent") {
            return "; for this lens that means what the range as a whole implies but no message states - a behaviour change no message mentions, a version bump without its changelog line - "
                   "and documentation the range leaves stale: a sentence of the repository's README or other documentation at HEAD, written by the range or older, that the range's code makes false "
                   "(a behaviour, an option, a path or a command described as it was before), or a list in it that something the range adds belongs in and is missing from";
        }
        return {};
    }

    namespace {
        // An optional string as the prompt prints it: None when absent.
        std::string OrNone(const std::optional<std::string>& value) {
            return value ? *value : "None";
        }

        // A string, or Error (TypeError): only a string is concatenated.
        const std::string& Text(const Json& value) {
            if (!value.is_string()) throw Dyn::Error("TypeError", std::format("can only concatenate str (not \"{}\") to str", Dyn::TypeName(value)));
            return value.get_ref<const std::string&>();
        }

        std::string JoinStrings(const Json& list, std::string_view separator) {
            std::vector<std::string> parts;
            for (const Json& item : list) parts.push_back(Text(item));
            return Dyn::Join(parts, separator);
        }

        std::int64_t IntItem(const Json& range, std::size_t index) {
            const Json& value = range.at(index);
            if (value.is_boolean()) return value.get<bool>() ? 1 : 0;
            return value.get<std::int64_t>();
        }
    }

    namespace {
        std::map<std::string, std::filesystem::path>& Sections() {
            static std::map<std::string, std::filesystem::path> files;
            return files;
        }
    }

    void SetLensSections(std::map<std::string, std::filesystem::path> files) {
        Sections() = std::move(files);
    }

    std::filesystem::path LensFile(std::string_view name) {
        return LensDir() / std::string(name);
    }

    std::string SystemText(std::string_view mode) {
        if (mode == "reply" || mode == "series") return Dyn::Replace(Dyn::ReadText(LensFile("_common.md")), "{{ARTIFACT_KIND}}", mode == "reply" ? "mailing-list reply" : "patch series");
        return Dyn::Replace(Dyn::ReadText(LensFile("_common-repo.md")), "{{ARTIFACT_KIND}}", "commit range");
    }

    namespace {
        std::string ArtifactLines(std::span<const std::string> lines) {
            std::vector<std::string> artifact;
            artifact.reserve(lines.size());
            for (std::size_t i = 0; i < lines.size(); ++i) artifact.push_back(std::format("{:04d}| {}", i + 1, lines[i]));
            return Dyn::Join(artifact, "\n");
        }

        std::string InventoryLines(const Json& units) {
            std::vector<std::string> inventory;
            for (const Json& unit : units) {
                const Json& range = Dyn::At(unit, "lines");
                inventory.push_back(std::format("- {} [{}-{}] {}", Dyn::Str(Dyn::At(unit, "id")), Dyn::Str(range.at(0)), Dyn::Str(range.at(1)), Dyn::Str(Dyn::At(unit, "excerpt"))));
            }
            return Dyn::Join(inventory, "\n");
        }
    }

    std::string RunLayerKernel(std::string_view mode, std::string_view artifactRel, std::string_view subsystem, std::string_view base, std::span<const std::string> reviewers, std::string_view date,
                               std::span<const std::string> trees, std::string_view hash, std::span<const std::string> lines, const Json& units, std::string_view refDigest,
                               std::span<const std::string> contextPaths) {
        std::vector<std::string> inputs;
        inputs.push_back(std::format("- The frozen artifact (review THIS, at hash {}): {}", hash,
                                     mode == "reply" ? std::format("the reply draft file {} - inlined below; nothing else is an input", artifactRel)
                                                     : std::format("the *.patch files in {} - inlined below in sorted order; nothing else in that dir is an input", artifactRel)));
        inputs.push_back(std::format("- Ledger: journal/{}/ledger.md (the only mutable journal file you may read)", subsystem));
        inputs.push_back(std::format("- Thread mboxes: journal/{}/captures/threads/", subsystem));
        inputs.push_back(std::format("- Evidence/proof artifacts: journal/{}/captures/ (index in the ledger)", subsystem));
        inputs.push_back(base.empty() ? std::string("- Target tree at the submission base: see the artifact") : std::format("- Target tree at the submission base: {}", base));
        if (!trees.empty()) inputs.push_back(std::format("- Trees: {}", Dyn::Join(trees, ", ")));
        if (!contextPaths.empty()) inputs.push_back(std::format("- Material the artifact discusses (read-only evidence; do not spend turns locating it): {}", Dyn::Join(contextPaths, ", ")));
        inputs.emplace_back("- History archaeology ONLY in work/milos-linux (work/linux is shallow; its history queries lie)");
        inputs.emplace_back("- lore.kernel.org ONLY via utilities/lore.py (an Anubis PoW wall blocks curl/WebFetch)");
        if (!reviewers.empty()) inputs.push_back(std::format("- Reviewers with a persona in this run: {}", Dyn::Join(reviewers, ", ")));
        inputs.push_back(std::format("- Run date: {}", date));
        return std::format("INPUTS:\n{}\n\nARTIFACT (frozen, hash {}), inlined with line numbers:\n{}\n\nINVENTORY - {} units, a MECHANICAL partition of the artifact (utilities/inventory.py: every non-blank line belongs to exactly one unit; fixed slots with lines 0-0 stand for what is NOT in the text):\n{}\n\n{}",
                           Dyn::Join(inputs, "\n"), hash, ArtifactLines(lines), units.size(), InventoryLines(units), refDigest);
    }

    Section ReadSection(const std::filesystem::path& file) {
        Section out;
        std::error_code error;
        const std::filesystem::file_status entry = std::filesystem::symlink_status(file, error);
        if (error && error != std::errc::no_such_file_or_directory && error != std::errc::not_a_directory) {
            out.present = true;
            out.problem = std::format("cannot be read ({})", error.message());
            return out;
        }
        if (!std::filesystem::exists(entry)) return out;
        out.present = true;
        if (!std::filesystem::is_regular_file(std::filesystem::status(file, error))) {
            out.problem = std::format("cannot be read ({})", error ? error.message() : std::string("not a regular file"));
            return out;
        }
        try {
            out.text = Dyn::ReadText(file);
        } catch (const Dyn::Error& failure) {
            out.problem = failure.Kind() == "UnicodeDecodeError" ? std::string("is not UTF-8") : std::string("cannot be read");
        }
        return out;
    }

    std::string Charter(std::string_view lensFile) {
        std::string text = Dyn::ReadText(LensFile(lensFile));
        if (const auto own = Sections().find(std::string(lensFile)); own != Sections().end()) {
            // Through the reader the config checks it with: a section the
            // config reported never reaches a run, and none is dropped here.
            const Section section = ReadSection(own->second);
            if (!section.problem.empty() || !section.present) {
                throw Dyn::Error("ValueError", std::format("lenses.{}.section: {} {}", Plan::LensName(lensFile), own->second.string(),
                                                           section.present ? section.problem : std::string("does not exist")));
            }
            while (text.ends_with('\n')) text.pop_back();
            text += std::format("\n\n{}", section.text);
        }
        return text;
    }

    std::string RunLayer(std::string_view artifactRel, std::string_view base, std::string_view date, std::span<const std::string> trees, std::string_view hash,
                         std::span<const std::string> lines, const Json& units, std::span<const std::string> contextPaths, std::string_view repoName, std::string_view subsystem) {
        std::vector<std::string> inputs;
        inputs.push_back(std::format("- The frozen artifact (review THIS, at hash {}): the *.patch files in {} - `git format-patch` of the commit range under review, inlined below in sorted order; nothing else in that dir is an input",
                                     hash, artifactRel));
        inputs.push_back(std::format("- Repository under review ({}), checked out at the range HEAD (the last commit of the artifact): {} - file content, history and blame come from this path; spell it exactly like this in every git -C call{}",
                                     repoName, Dyn::Join(trees, ", "), !trees.empty() && trees.front() == "." ? " (`.` is the working directory)" : ""));
        inputs.push_back(base.empty() ? std::string("- Range base: the base-commit line of the last patch")
                                      : std::format("- Range base (the state before the first commit; `git -C <tree> show <base>:<path>`): {}", base));
        if (!subsystem.empty()) {
            inputs.push_back(std::format("- Ledger: journal/{}/ledger.md (the only mutable journal file you may read)", subsystem));
            inputs.push_back(std::format("- Evidence/proof artifacts: journal/{}/captures/ (index in the ledger)", subsystem));
        }
        if (!contextPaths.empty()) {
            inputs.push_back(std::format("- Material the artifact discusses (read-only evidence; do not spend turns locating it): {}", Dyn::Join(contextPaths, ", ")));
        }
        inputs.push_back("- No mailing list, no network beyond the application under test: what is not on disk or in the running application is unverifiable and becomes a note");
        inputs.push_back(std::format("- Run date: {}", date));
        std::vector<std::string> artifact;
        artifact.reserve(lines.size());
        for (std::size_t i = 0; i < lines.size(); ++i) artifact.push_back(std::format("{:04d}| {}", i + 1, lines[i]));
        std::vector<std::string> inventory;
        for (const Json& unit : units) {
            const Json& range = Dyn::At(unit, "lines");
            inventory.push_back(std::format("- {} [{}-{}] {}", Dyn::Str(Dyn::At(unit, "id")), Dyn::Str(range.at(0)), Dyn::Str(range.at(1)), Dyn::Str(Dyn::At(unit, "excerpt"))));
        }
        return std::format("INPUTS:\n{}\n\nARTIFACT (frozen, hash {}), inlined with line numbers:\n{}\n\nINVENTORY - {} units, a MECHANICAL partition of the artifact (every non-blank line belongs to exactly one unit; fixed slots with lines 0-0 stand for what is NOT in the text):\n{}",
                           Dyn::Join(inputs, "\n"), hash, Dyn::Join(artifact, "\n"), units.size(), Dyn::Join(inventory, "\n"));
    }

    std::string AppBlock(const Json& functional, const std::optional<std::string>& loginFixture, const std::optional<std::string>& totpCommand, bool slots) {
        const Json& f = Dyn::Or(functional, Dyn::EmptyDict());
        std::vector<std::string> lines = {"APPLICATION UNDER TEST (this lens drives it with the Playwright MCP tools mcp__playwright__*):"};
        if (slots) {
            lines.emplace_back("- The application: a stack of this pass's own (the application, its API, its database and a login), one of several the operator brought up side by side from the tree named under INPUTS at the range HEAD; STACK FOR THIS PASS, at the end of the prompt, names its URL, the other origins it answers on and its login (the driver verified each stack answers before the gate started)");
        } else {
            lines.push_back(std::format("- The application: {} - served from the tree named under INPUTS at the range HEAD (the driver verified the tree is at that HEAD and that this URL answers before the gate started)",
                                        Dyn::Str(Dyn::Get(f, "appUrl"))));
            if (Dyn::Truthy(Dyn::Get(f, "apiUrls"))) lines.push_back(std::format("- Other local origins you may call (the API, mail): {}", JoinStrings(Dyn::At(f, "apiUrls"), ", ")));
            if (loginFixture && !loginFixture->empty()) {
                lines.push_back(std::format("- Login: the fixture {} (JSON: email, password, totpSecret - a throwaway test account on the local stack); read it with the Read tool, and for the one-time code run exactly `{}` (prints a 6-digit code and the seconds left in its window; regenerate when it rolled over)",
                                            *loginFixture, OrNone(totpCommand)));
            } else {
                lines.emplace_back("- Login: no fixture was found on disk; what the application shows without a session is what you can exercise, and a behaviour behind a login is an `unverified` note with n/a");
            }
        }
        if (Dyn::Truthy(Dyn::Get(Dyn::Or(Dyn::Get(f, "login"), Dyn::EmptyDict()), "notes"))) {
            lines.push_back(std::format("- Login notes: {}", Text(Dyn::At(Dyn::At(f, "login"), "notes"))));
        }
        if (Dyn::Truthy(Dyn::Get(f, "notes"))) lines.push_back(std::format("- Notes from the repository owner: {}", Text(Dyn::At(f, "notes"))));
        lines.push_back(std::format("- Rules: navigate only to the origins named here; the browser and the stack (the application, its database, the account) are yours alone while this pass runs, but the stack is not reset between passes: earlier passes of this gate may have left records in it and later ones will see what you leave - create only what you need, name it with your unit id, never delete or change what you did not create in this pass, and leave the account as you found it (where the range makes you change its password, an MFA factor, an organisation setting or the subscription, restore it; where you cannot, say so in an `info` note). Never sign up a new account unless the range is about signup. {}",
                                    ShotRules));
        return Dyn::Join(lines, "\n");
    }

    std::string StackText(const Json& stack, const std::optional<std::string>& totpCommand) {
        std::vector<std::string> lines = {
            std::format("STACK FOR THIS PASS ({}, yours alone while this pass runs):", Dyn::Str(Dyn::At(stack, "id"))),
            std::format("- The application: {}", Dyn::Str(Dyn::At(stack, "appUrl"))),
        };
        if (Dyn::Truthy(Dyn::Get(stack, "apiUrls"))) lines.push_back(std::format("- Other local origins you may call (the API, mail): {}", JoinStrings(Dyn::At(stack, "apiUrls"), ", ")));
        if (Dyn::Truthy(Dyn::Get(stack, "login"))) {
            lines.push_back(std::format("- Login: the fixture {} (JSON: email, password, totpSecret - a throwaway test account on this stack); read it with the Read tool, and for the one-time code run exactly `{}` (prints a 6-digit code and the seconds left in its window; regenerate when it rolled over)",
                                        Dyn::Str(Dyn::At(stack, "login")), OrNone(totpCommand)));
        } else {
            lines.emplace_back("- Login: this stack has no login fixture; what the application shows without a session is what you can exercise, and a behaviour behind a login is an `unverified` note with n/a");
        }
        return Dyn::Join(lines, "\n");
    }

    std::string DbBlock(const Json& supabase, std::string_view sqlCommand, const std::optional<std::string>& dbUser, bool withApp,
                        const std::optional<std::string>& checked, std::optional<bool> bypass) {
        const Json& s = Dyn::Or(supabase, Dyn::EmptyDict());
        std::string role;
        if (dbUser && !dbUser->empty()) {
            role = std::format("The connection is the role `{}`{}", *dbUser,
                               !bypass ? "." : (*bypass ? ", which bypasses row-level security." : ", which row-level security applies to."));
        } else {
            role = "The connection's role differs between the stacks: `select current_user` says which is yours, and its pg_roles row whether row-level security applies to it.";
        }
        std::vector<std::string> lines = {
            std::format("DATABASE UNDER TEST (this lens runs SQL against it with the exact command `{}`):", sqlCommand),
            std::format("- The database: the Postgres of the local Supabase stack the operator brought up from the tree named under INPUTS - a throwaway stack, never a hosted project. Checked by the driver before this gate: {}. {}",
                        checked && !checked->empty() ? *checked : std::string("nothing (a dry run)"), role),
            std::format("- Run SQL with exactly `{} <<'SQL'`, the statements on the lines after it, and a last line `SQL`. Every call is ONE transaction that the helper rolls back at its end: what a statement writes is seen by the later statements of the same call and by nothing else - not by the application, not by the other passes running at the same time, not by your next call. So a proof goes into one call: set up the state, act, read the outcome. BEGIN, COMMIT, ROLLBACK, END, ABORT, PREPARE TRANSACTION and COPY are refused (SAVEPOINT and ROLLBACK TO are fine); the first statement that fails stops the call.",
                        sqlCommand),
            "- Acting as a caller of the API: `set local role authenticated;` then `select set_config('request.jwt.claims', '{\"sub\":\"<a user id from auth.users>\",\"role\":\"authenticated\"}', true);` makes row-level security, auth.uid() and auth.jwt() behave as for that signed-in user; `set local role anon` as for a visitor without a session; `set local role service_role` as the service key. Say in your evidence which role each query ran as.",
            std::format("- Limits: statement_timeout {} s and lock_timeout {} s per statement; at most {} rows of a result are printed. A lock you take (DDL, an UPDATE) holds until your call ends while the other passes and the application wait on it - keep such calls short.",
                        PgWire::StatementTimeoutS, PgWire::LockTimeoutS, PgWire::MaxRows),
            "- Evidence: the SQL you ran and the lines the helper printed for it - quote both in the finding or the coverage basis. Output that starts `review-gates sql: NO DATABASE` means the database did not answer: what rests on it is unverified, never clear.",
        };
        if (withApp) {
            lines.emplace_back("- Nothing you write here reaches the application: create what the browser must see through the application itself, and use this database to read back what the application persisted and to inspect state no screen shows.");
        }
        if (Dyn::Truthy(Dyn::Get(s, "notes"))) lines.push_back(std::format("- Notes from the repository owner: {}", Text(Dyn::At(s, "notes"))));
        return Dyn::Join(lines, "\n");
    }

    std::string LensLayer(std::string_view lensFile, std::string_view charterText, std::string_view dispositionsBlock, std::string_view app,
                          std::string_view wholeSummary, std::string_view db, std::string_view persona, std::string_view corpus) {
        std::vector<std::string> parts;
        if (!persona.empty()) {
            parts.push_back(std::format("Your persona: {}. You ARE this person, reviewing what they will actually read. Calibrate ONLY on mail they actually wrote (their replies to us and to recent similar series - fetch via utilities/lore.py).", persona));
            if (!corpus.empty()) parts.push_back(std::format("CALIBRATION MAP - a lore search listing of this person's recent mail (fetch the bodies you need):\n{}", Dyn::Slice(corpus, 0, 6000)));
        }
        parts.push_back(std::format("YOUR CHARTER (process/lenses/{}), verbatim:\n\n{}", lensFile, Dyn::Strip(charterText)));
        if (!app.empty()) parts.emplace_back(app);
        if (!db.empty()) parts.emplace_back(db);
        parts.emplace_back(dispositionsBlock);
        if (!wholeSummary.empty()) {
            parts.push_back(std::format("The whole pass of this lens on this hash concluded (the constraints your block pass rests on):\n{}", Dyn::Slice(wholeSummary, 0, 2500)));
        }
        return Dyn::Join(parts, "\n\n");
    }

    std::string Tail(const Json& job, const Json& units, std::span<const std::string> lines, std::string_view wholeSummary) {
        const std::string lensFile = Dyn::At(job, "lensFile").get<std::string>();
        const Json& kind = Dyn::At(job, "kind");
        const Plan::Lens& lens = Plan::LensOf(lensFile);
        const std::string_view vocab = lensFile == Plan::PersonaLens ? PersonaVocab : lens.kernel ? GenericVocabKernel : GenericVocab;
        if (kind == "whole") {
            const std::string_view whole = lens.whole;
            std::string_view text;
            if (whole == "first-repo") {
                text = WholeFirstRepo;
            } else if (whole == "functional") {
                text = WholeFunctional;
            } else if (whole == "first") {
                text = WholeFirst;
            } else if (whole == "all") {
                text = WholeAll;
            } else if (whole == "persona") {
                text = WholePersona;
            } else {
                throw Dyn::Error("KeyError", Dyn::ReprValue(whole.empty() ? Json() : Json(whole)));
            }
            std::vector<std::string> listed;
            const Json& expected = Dyn::At(job, "expectedIds");
            for (const Json& unit : units) {
                if (Dyn::In(Dyn::At(unit, "id"), expected)) listed.push_back(std::format("- {} [0-0] {}", Dyn::Str(Dyn::At(unit, "id")), Dyn::Str(Dyn::At(unit, "excerpt"))));
            }
            return std::format("{}\n{}\nUnits to cover:\n{}", text, vocab, Dyn::Join(listed, "\n"));
        }
        const Json* found = nullptr;
        for (const Json& unit : units) {
            if (Dyn::Equal(Dyn::At(unit, "id"), Dyn::At(job, "unit"))) {
                found = &unit;
                break;
            }
        }
        if (!found) throw Dyn::Error("StopIteration", "");
        const Json& u = *found;
        const std::string id = Dyn::Str(Dyn::At(u, "id"));
        if (kind == "slot") {
            const std::string description = Dyn::Replace(Text(Dyn::At(u, "excerpt")), "FIXED SLOT: ", "");
            return std::format("SCOPE - SLOT PASS, unit \"{}\": this unit has no lines; it stands for a question about the whole artifact: {}. Answer it for your lens{}. Coverage: exactly this one unit.\n{}",
                               id, description, SlotDuty(lensFile, id), vocab);
        }
        const Json& range = Dyn::At(u, "lines");
        const std::int64_t a = IntItem(range, 0);
        const std::int64_t b = IntItem(range, 1);
        const Json& unitKind = Dyn::Get(job, "unitKind");
        const bool prose = unitKind == "text" || unitKind == "doc";
        std::string_view hint;
        if (id == "anchor") {
            hint = HintAnchor;
        } else if (id == "refs") {
            hint = HintRefs;
        } else if (id.ends_with(":outside")) {
            hint = lens.kernel ? HintOutsideKernel : HintOutside;
        } else if (id.ends_with(":absent")) {
            hint = lens.kernel ? HintAbsentKernel : HintAbsent;
        } else if (lensFile == Plan::FunctionalLens) {
            hint = FunctionalBlockHint;
        } else if (unitKind == "text") {
            hint = lens.kernel ? TextBlockHint : TextBlockHintRepo;
        } else if (unitKind == "doc") {
            hint = DocBlockHintRepo;
        }
        const std::string text = Plan::UnitText(lines, u);
        // The kernel modes' block judges a claim, a sentence or a hunk in one
        // phrase; the push gates' says which the unit is.
        const std::string_view against = lens.kernel ? "a claim at its source, a sentence against its proof obligation, a hunk against the standard"
                                         : prose      ? "a claim at its source, a sentence against its proof obligation"
                                                      : "a hunk against the standard";
        const std::string scope = std::format("SCOPE - BLOCK PASS, unit \"{}\" [lines {}-{}]: judge ONLY this unit, with your full attention by your charter - {} - reading the rest of the artifact only as context. Do not re-litigate the approach as a whole{}. Coverage: exactly this one unit.",
                                              id, a, b, against, wholeSummary.empty() ? "" : " - the whole pass of this lens concluded as stated above");
        return std::format("{}{}\n\nUNIT TEXT (verbatim, lines {}-{}):\n{}\n\n{}", scope, hint.empty() ? std::string() : std::format("\n{}", hint), a, b, text, vocab);
    }

    std::string BudgetLine(const Json& job, bool kernel) {
        return std::format("\n\nTool-call budget for this pass: {} (every tool call is one request; the pipeline stops the process at that count and a stopped pass "
                           "returns NOTHING - the unit is then unaddressed and the lens NOT RETURNED). Batch independent reads into one call{} and return the structured output with margin to spare.",
                           Dyn::Str(Dyn::Get(job, "maxTurns")), kernel ? ", read the prefetched raw files instead of fetching," : "");
    }

    std::string SystemPrompt(std::string_view systemText, std::string_view run, std::string_view lens) {
        return std::format("{}{}{}{}{}", systemText, SepRun, run, SepLens, lens);
    }

    std::string UserPrompt(std::string_view tail, const Json& job, std::string_view stack, bool kernel) {
        return std::format("{}{}{}\n\nReturn the structured output described in your instructions.\n", tail, stack.empty() ? std::string() : std::format("\n\n{}", stack),
                           Dyn::Truthy(job) ? BudgetLine(job, kernel) : std::string());
    }
}