pi2web 0.2.0 → 0.2.6

package/dist/collab/routes.js

@@ -0,0 +1,285 @@
+import { ValidationError } from './validate.js';
+import { COLLAB_ERRORS } from './types.js';
+const ok = (payload, status = 200) => ({ status, payload: { data: payload } });
+const forbidden = (message) => ({
+    status: 403,
+    payload: { error: { code: COLLAB_ERRORS.forbidden, message } }
+});
+/**
+ * HTTP surface for the collaboration hub. Two credentials are accepted:
+ * the pairing code (a human, full control) and a participant token (one agent, its own session only).
+ * Session creation, participant registration, forced advances, and rulings are human-only by design.
+ */
+export class CollabRouter {
+    hub;
+    deps;
+    constructor(hub, deps) {
+        this.hub = hub;
+        this.deps = deps;
+    }
+    async handle(input) {
+        const { method, url, parts, token } = input;
+        if (parts[0] !== 'api' || parts[1] !== 'v1' || parts[2] !== 'collab')
+            return undefined;
+        const isHuman = token ? await this.deps.verifyHuman(token) : this.deps.noAuth;
+        let participant;
+        if (!isHuman) {
+            try {
+                participant = this.hub.authenticate(token);
+            }
+            catch {
+                return {
+                    status: 401,
+                    payload: {
+                        error: { code: 'UNAUTHORIZED', message: 'A pairing code or participant token is required' }
+                    },
+                    authFailed: true
+                };
+            }
+        }
+        try {
+            return await this.route({ method, url, parts, body: input.body, isHuman, participant });
+        }
+        catch (error) {
+            return this.errorResult(error);
+        }
+    }
+    async route(ctx) {
+        const { method, url, parts, isHuman, participant } = ctx;
+        const human = (action) => {
+            if (!isHuman)
+                throw Object.assign(new Error(`${action} is reserved for humans`), {
+                    code: COLLAB_ERRORS.humanOnly,
+                    httpStatus: 403
+                });
+        };
+        const asParticipant = () => {
+            if (!participant)
+                throw Object.assign(new Error('This endpoint requires a participant token'), {
+                    code: COLLAB_ERRORS.forbidden,
+                    httpStatus: 403
+                });
+            return participant;
+        };
+        const scoped = (sessionId) => {
+            if (participant && participant.sessionId !== sessionId)
+                throw Object.assign(new Error('Collaboration session not found'), {
+                    code: COLLAB_ERRORS.sessionNotFound,
+                    httpStatus: 404
+                });
+        };
+        const collabAgent = (agentId) => {
+            if (typeof agentId !== 'string' || !this.deps.isCollabAgent(agentId))
+                throw Object.assign(new Error('A collaboration seat requires an existing, dedicated collaboration Agent (profile=collab). Create one from the collaboration board, then register or rebind this seat to it.'), { code: COLLAB_ERRORS.forbidden, httpStatus: 403 });
+        };
+        const number = (name, fallback) => {
+            const raw = url.searchParams.get(name);
+            const value = raw === null ? fallback : Number(raw);
+            return Number.isFinite(value) ? value : fallback;
+        };
+        // /api/v1/collab/escalations[/{id}/resolve]
+        if (parts[3] === 'escalations') {
+            if (method === 'GET' && parts.length === 4) {
+                human('Listing escalations');
+                return ok(this.hub.listEscalations({
+                    status: url.searchParams.get('status') ?? undefined,
+                    sessionId: url.searchParams.get('sessionId') ?? undefined
+                }));
+            }
+            if (method === 'GET' && parts.length === 5) {
+                human('Reading an escalation');
+                return ok(this.hub.getEscalation(parts[4]));
+            }
+            if (method === 'POST' && parts[5] === 'resolve') {
+                human('Ruling on an escalation');
+                return ok(await this.hub.resolveEscalation(parts[4], await ctx.body()));
+            }
+            return undefined;
+        }
+        if (parts[3] !== 'sessions')
+            return undefined;
+        if (method === 'POST' && parts.length === 4) {
+            human('Creating a collaboration session');
+            return ok(await this.hub.createSession(await ctx.body(), this.deps.resolveCwd), 201);
+        }
+        if (method === 'GET' && parts.length === 4) {
+            if (isHuman)
+                return ok(this.hub.listSessions({
+                    status: url.searchParams.get('status') ?? undefined,
+                    kind: url.searchParams.get('kind') ?? undefined,
+                    limit: number('limit', 50),
+                    offset: number('offset', 0)
+                }));
+            return ok([this.hub.getSession(asParticipant().sessionId)]);
+        }
+        const sessionId = parts[4];
+        if (!sessionId)
+            return undefined;
+        scoped(sessionId);
+        const tail = parts[5], sub = parts[6];
+        // Only these tails have sub-resources. Without this, `POST .../advance/anything` would be treated as an
+        // advance, and any future sub-path would be silently answered by the flat handler above it.
+        if (sub && !['participants', 'issues', 'debates'].includes(tail ?? ''))
+            return undefined;
+        if (method === 'GET' && !tail)
+            return ok({
+                ...this.hub.getSession(sessionId),
+                progress: this.hub.progress(sessionId),
+                participants: isHuman
+                    ? this.hub.participantsForHuman(sessionId)
+                    : this.hub.store.listParticipants(sessionId)
+            });
+        if (tail === 'participants') {
+            // Sub-resources first: an unguarded register branch would swallow .../participants/{id}/binding and /budget
+            // and answer them with "role is required", which is how both repair paths became unreachable over HTTP.
+            // .../participants/{participantId}/binding — repairs a seat that was registered with the wrong binding.
+            if (method === 'POST' && sub && parts[7] === 'binding') {
+                human('Rebinding a participant');
+                const body = await ctx.body();
+                if (typeof body?.agentId === 'string')
+                    collabAgent(body.agentId);
+                const { participant: bound, token } = this.hub.rebindParticipant(sessionId, sub, body);
+                return ok({ participant: bound, participantToken: token });
+            }
+            // .../participants/{participantId}/budget — un-blocks a seat that spent its budget, at any time.
+            if (method === 'POST' && sub && parts[7] === 'budget') {
+                human('Raising a token budget');
+                return ok(this.hub.raiseParticipantBudget(sessionId, sub, await ctx.body()));
+            }
+            // An unknown sub-resource must 404, not fall through to "register a participant".
+            if (sub)
+                return undefined;
+            if (method === 'POST') {
+                human('Registering a participant');
+                const body = await ctx.body();
+                if (typeof body?.agentId === 'string')
+                    collabAgent(body.agentId);
+                const { participant: created, token } = this.hub.addParticipant(sessionId, body);
+                // The plaintext token is returned exactly once; only its hash is stored.
+                return ok({ participant: created, participantToken: token, briefing: this.hub.digest(created) }, 201);
+            }
+            if (method === 'GET')
+                return ok(isHuman
+                    ? this.hub.participantsForHuman(sessionId)
+                    : this.hub.store.listParticipants(sessionId).map(entry => ({ ...entry })));
+        }
+        if (method === 'POST' && tail === 'advance') {
+            human('Advancing a phase');
+            return ok(await this.hub.advance(sessionId, await ctx.body()));
+        }
+        if (method === 'POST' && tail === 'retry-waiting') {
+            human('Retrying waiting Agents');
+            return ok(this.hub.retryWaiting(sessionId, await ctx.body()));
+        }
+        if (method === 'POST' && tail === 'policy') {
+            human('Changing the policy');
+            return ok(this.hub.updatePolicy(sessionId, await ctx.body()));
+        }
+        if (method === 'POST' && tail === 'open-round') {
+            human('Opening a round');
+            return ok(await this.hub.openRound(sessionId));
+        }
+        if (method === 'POST' && tail === 'recheck') {
+            human('Reopening a finished review');
+            return ok(await this.hub.startRecheck(sessionId, await ctx.body()));
+        }
+        if (method === 'GET' && tail === 'events')
+            return ok(url.searchParams.has('tail')
+                ? this.hub.recentEvents(sessionId, number('tail', 200), participant)
+                : this.hub.events(sessionId, number('since', 0), number('limit', 500), participant));
+        if (method === 'GET' && tail === 'digest')
+            return ok(this.hub.digest(asParticipant()));
+        if (method === 'GET' && tail === 'issues' && !sub)
+            return ok(isHuman ? this.hub.store.listIssues(sessionId) : this.hub.listIssues(asParticipant()));
+        if (method === 'GET' && tail === 'issues' && sub)
+            return ok(this.hub.issueDetail(sessionId, sub, participant));
+        if (method === 'POST' && tail === 'issues' && parts[7] === 'withdraw')
+            return ok(await this.hub.withdrawIssue(asParticipant(), sub));
+        if (method === 'GET' && tail === 'review-consensus')
+            return ok(this.hub.reviewConsensus(sessionId, participant));
+        // Round history is a close-out view over every wave's findings; a participant token reading it during a live
+        // round would see the other reviewers' sealed issues, so it stays human-only like /report.
+        if (method === 'GET' && tail === 'review-rounds') {
+            human('Reading the round history');
+            return ok(this.hub.reviewRounds(sessionId));
+        }
+        if (method === 'POST' && tail === 'issue-votes')
+            return ok(await this.hub.submitIssueVotes(asParticipant(), await ctx.body()));
+        if (method === 'POST' && tail === 'merge-votes')
+            return ok(await this.hub.submitMergeVotes(asParticipant(), await ctx.body()));
+        if (method === 'POST' && tail === 'issue-discussions')
+            return ok(await this.hub.submitIssueDiscussions(asParticipant(), await ctx.body()));
+        if (method === 'POST' && tail === 'nominations')
+            return ok(await this.hub.submitNominations(asParticipant(), await ctx.body()), 201);
+        if (method === 'GET' && tail === 'criteria')
+            return ok(this.hub.criteria(sessionId, participant));
+        if (method === 'POST' && tail === 'votes')
+            return ok(await this.hub.submitVotes(asParticipant(), await ctx.body()));
+        if (method === 'GET' && tail === 'votes')
+            return ok(this.hub.votes(sessionId, participant));
+        if (method === 'POST' && tail === 'scores')
+            return ok(await this.hub.submitScores(asParticipant(), await ctx.body()));
+        if (method === 'GET' && tail === 'analysis')
+            return ok(this.hub.analysis(sessionId, participant));
+        if (method === 'GET' && tail === 'debates')
+            return ok(this.hub.store.listDebates(sessionId));
+        if (method === 'POST' && tail === 'debates' && parts[7] === 'arguments')
+            return ok(await this.hub.submitDebateArgument(asParticipant(), sub, await ctx.body()), 201);
+        if (method === 'POST' && tail === 'finalize') {
+            human('Finalizing a scoring session');
+            return ok(await this.hub.finalizeScoring(sessionId, await ctx.body()));
+        }
+        if (method === 'POST' && tail === 'ready')
+            return ok(await this.hub.markImplementationReady(asParticipant(), await ctx.body()));
+        if (method === 'POST' && tail === 'findings')
+            return ok(await this.hub.submitFindings(asParticipant(), await ctx.body()), 201);
+        if (method === 'POST' && tail === 'escalations')
+            return ok(await this.hub.raiseEscalation(asParticipant(), await ctx.body()), 202);
+        // The report is the human close-out view: it lists every issue and escalation, which would defeat blind
+        // collection if a participant token could read it while the round is still open.
+        if (method === 'GET' && tail === 'report') {
+            human('Reading the session report');
+            const reportSession = this.hub.getSession(sessionId);
+            return ok({
+                session: reportSession,
+                progress: this.hub.progress(sessionId),
+                issues: this.hub.store.listIssues(sessionId),
+                reviewSummary: reportSession.kind === 'review' ? this.hub.reviewSummary(sessionId) : undefined,
+                escalations: this.hub.listEscalations({ sessionId })
+            });
+        }
+        return undefined;
+    }
+    /** Every failure carries a stable code so an agent can branch on it instead of parsing prose. */
+    errorResult(error) {
+        if (error instanceof ValidationError)
+            return {
+                status: 422,
+                payload: { error: { code: error.code, message: error.message, fieldErrors: error.fieldErrors } }
+            };
+        const value = error, code = value?.code;
+        const status = Number.isInteger(value?.httpStatus)
+            ? value.httpStatus
+            : code === COLLAB_ERRORS.conflict ||
+                code === COLLAB_ERRORS.staleBaseline ||
+                code === COLLAB_ERRORS.wrongPhase ||
+                code === COLLAB_ERRORS.humanRulingFinal
+                ? 409
+                : code === COLLAB_ERRORS.budgetExhausted
+                    ? 429
+                    : code?.endsWith('NOT_FOUND')
+                        ? 404
+                        : 400;
+        const extra = code === COLLAB_ERRORS.staleBaseline && value.currentBaseline
+            ? { currentBaseline: value.currentBaseline }
+            : {};
+        if (status === 403 && !code)
+            return forbidden(String(value?.message ?? 'Forbidden'));
+        return {
+            status,
+            payload: {
+                error: { code: code ?? 'BAD_REQUEST', message: String(value?.message ?? 'Request failed'), ...extra }
+            }
+        };
+    }
+}

package/dist/collab/schemas.js

@@ -0,0 +1,281 @@
+import { CATEGORIES, DEBATE_STANCES, ESCALATION_KINDS, REGISTRABLE_ROLES, REQUIRED_ACTIONS, SEVERITIES, VOTE_STANCES } from './types.js';
+import { anyJson, arr, bool, num, obj, oneOf, optional, record, refine, str, withDefault } from './validate.js';
+/**
+ * Request schemas for every collaboration endpoint. They are deliberately strict:
+ * a rejected payload comes back with per-field codes so an agent can repair and retry
+ * instead of guessing what the hub wanted.
+ */
+const clientRequestId = () => str({ min: 8, max: 200 });
+const usage = () => optional(obj({
+    inputTokens: optional(num({ min: 0, max: 100_000_000, integer: true })),
+    outputTokens: optional(num({ min: 0, max: 100_000_000, integer: true })),
+    totalTokens: optional(num({ min: 0, max: 100_000_000, integer: true }))
+}));
+const codeLocation = () => obj({
+    path: str({ min: 1, max: 400 }),
+    startLine: optional(num({ integer: true, min: 1 })),
+    endLine: optional(num({ integer: true, min: 1 }))
+});
+/** Evidence must point at a file: an unanchored claim is indistinguishable from a hallucination. */
+const evidenceItem = () => obj({
+    path: str({ min: 1, max: 400 }),
+    startLine: optional(num({ integer: true, min: 1 })),
+    endLine: optional(num({ integer: true, min: 1 })),
+    excerpt: optional(str({ max: 2000 }))
+});
+export const findingSchema = obj({
+    externalId: optional(str({ max: 100 })),
+    title: str({ min: 8, max: 200 }),
+    severity: oneOf(SEVERITIES),
+    category: oneOf(CATEGORIES),
+    requiredAction: withDefault(oneOf(REQUIRED_ACTIONS), () => 'should_fix'),
+    confidence: optional(num({ min: 0, max: 1 })),
+    location: codeLocation(),
+    evidence: str({ min: 10, max: 4000 }),
+    impact: optional(str({ max: 2000 })),
+    suggestion: optional(str({ max: 4000 })),
+    targetParticipantId: optional(str({ max: 100 }))
+});
+export const findingsRequest = obj({
+    clientRequestId: clientRequestId(),
+    baselineId: str({ min: 1, max: 100 }),
+    findings: arr(findingSchema, { max: 50 }),
+    /** On a later review round, the original reporter verifies each previously confirmed issue. */
+    rechecks: withDefault(arr(obj({
+        issueId: str({ min: 1, max: 100 }),
+        outcome: oneOf(['resolved', 'still_present']),
+        rationale: str({ min: 10, max: 4000 })
+    }), { max: 100 }), () => []),
+    reviewComplete: withDefault(bool(), () => false),
+    usage: usage()
+});
+/** Batched after blind collection: one request validates every issue this reviewer did not report. */
+export const issueVotesRequest = obj({
+    clientRequestId: clientRequestId(),
+    votes: arr(obj({
+        issueId: str({ min: 1, max: 100 }),
+        stance: oneOf(['approve', 'reject']),
+        rationale: optional(str({ max: 4000 }))
+    }), { max: 200 }),
+    mergeProposals: withDefault(arr(obj({ issueIds: arr(str({ min: 1, max: 100 }), { min: 2, max: 20 }), rationale: str({ min: 10, max: 2000 }) }), { max: 50 }), () => []),
+    complete: withDefault(bool(), () => true),
+    usage: usage()
+});
+export const mergeVotesRequest = obj({
+    clientRequestId: clientRequestId(),
+    votes: arr(obj({
+        proposalId: str({ min: 1, max: 100 }),
+        stance: oneOf(['approve', 'reject']),
+        rationale: optional(str({ max: 4000 }))
+    }), { max: 100 }),
+    complete: withDefault(bool(), () => true),
+    usage: usage()
+});
+export const issueDiscussionsRequest = obj({
+    clientRequestId: clientRequestId(),
+    discussions: withDefault(arr(obj({
+        issueId: str({ min: 1, max: 100 }),
+        argument: str({ min: 20, max: 4000 }),
+        respondingTo: optional(str({ max: 100 }))
+    }), { max: 200 }), () => []),
+    /** The reporter's way out of a finding it no longer stands by, in the same call that defends the rest. */
+    withdrawals: withDefault(arr(obj({ issueId: str({ min: 1, max: 100 }), rationale: str({ min: 10, max: 4000 }) }), { max: 200 }), () => []),
+    complete: withDefault(bool(), () => true),
+    usage: usage()
+});
+export const escalationRequest = obj({
+    clientRequestId: clientRequestId(),
+    kind: oneOf(ESCALATION_KINDS),
+    refId: optional(str({ max: 100 })),
+    summary: str({ min: 20, max: 2000 }),
+    positions: withDefault(arr(obj({
+        participantId: str({ min: 1, max: 100 }),
+        stance: str({ max: 200 }),
+        rationale: str({ min: 10, max: 2000 })
+    }), { max: 20 }), () => []),
+    question: str({ min: 10, max: 1000 }),
+    options: withDefault(arr(str({ min: 1, max: 200 }), { max: 10 }), () => []),
+    urgency: withDefault(oneOf(['low', 'normal', 'high']), () => 'normal'),
+    usage: usage()
+});
+/**
+ * A scale is only usable as a whole: `{min:10,max:1,step:1}` passes every per-field range check and then
+ * produces a session in which every possible score fails validation. The span must be positive and
+ * at least one step wide.
+ */
+const scoringScale = refine(obj({ min: num({ min: 0, max: 1000 }), max: num({ min: 1, max: 1000 }), step: num({ min: 0.01, max: 100 }) }), scale => {
+    const errors = [];
+    if (scale.max <= scale.min)
+        errors.push({
+            path: 'max',
+            code: 'OUT_OF_ORDER',
+            message: `Expected max (${scale.max}) to be greater than min (${scale.min})`,
+            expected: `> ${scale.min}`
+        });
+    else if (scale.step > scale.max - scale.min)
+        errors.push({
+            path: 'step',
+            code: 'TOO_LARGE',
+            message: `Expected a step that fits inside the ${scale.min}-${scale.max} range`,
+            expected: `<= ${scale.max - scale.min}`
+        });
+    return errors;
+});
+const scoringPolicyPatch = refine(obj({
+    minCriteria: optional(num({ integer: true, min: 1, max: 20 })),
+    maxCriteria: optional(num({ integer: true, min: 1, max: 20 })),
+    approvalThreshold: optional(num({ min: 0.5, max: 1 })),
+    maxVotingRounds: optional(num({ integer: true, min: 1, max: 10 })),
+    scale: optional(scoringScale),
+    convergenceRange: optional(num({ min: 0, max: 1000 })),
+    maxDebateRounds: optional(num({ integer: true, min: 0, max: 10 })),
+    blindScoring: optional(bool())
+}), patch => patch.minCriteria !== undefined &&
+    patch.maxCriteria !== undefined &&
+    patch.minCriteria > patch.maxCriteria
+    ? [
+        {
+            path: 'maxCriteria',
+            code: 'OUT_OF_ORDER',
+            message: `Expected maxCriteria (${patch.maxCriteria}) to be at least minCriteria (${patch.minCriteria})`,
+            expected: `>= ${patch.minCriteria}`
+        }
+    ]
+    : undefined);
+export const policyPatch = obj({
+    maxIssueRounds: optional(num({ integer: true, min: 1, max: 20 })),
+    maxTotalRounds: optional(num({ integer: true, min: 1, max: 50 })),
+    overdueWarningSec: optional(num({ integer: true, min: 60, max: 86_400 })),
+    autoEscalateOnDeadlock: optional(bool()),
+    blindFindings: optional(bool()),
+    consensusReview: optional(bool()),
+    maxConsensusRounds: optional(num({ integer: true, min: 1, max: 10 })),
+    implementationFirst: optional(bool()),
+    tokenBudgetPerParticipant: optional(num({ integer: true, min: 1000, max: 100_000_000 })),
+    scoring: optional(scoringPolicyPatch)
+});
+/** The implementer's "I am done, call the reviewers" signal. It is what turns build-then-review into one loop. */
+export const readyRequest = obj({
+    clientRequestId: clientRequestId(),
+    summary: str({ min: 10, max: 4000 }),
+    changes: withDefault(arr(obj({ path: str({ min: 1, max: 400 }), summary: str({ min: 5, max: 1000 }) }), { max: 100 }), () => []),
+    codeRef: optional(obj({ commit: optional(str({ max: 100 })), dirtyHash: optional(str({ max: 200 })) })),
+    usage: usage()
+});
+/** Human-only restart of a finished review: review current code, or let selected developers fix first. */
+export const recheckRequest = obj({
+    mode: oneOf(['review_only', 'fix_then_review']),
+    implementerParticipantIds: withDefault(arr(str({ min: 1, max: 100 }), { max: 20 }), () => [])
+});
+export const createSessionRequest = obj({
+    kind: oneOf(['review', 'scoring']),
+    title: str({ min: 3, max: 200 }),
+    workspaceId: str({ min: 1, max: 200 }),
+    relativeCwd: withDefault(str({ max: 400 }), () => '.'),
+    subject: obj({
+        type: oneOf(['diff', 'paths', 'commit_range', 'free']),
+        value: str({ min: 1, max: 2000 }),
+        notes: optional(str({ max: 4000 }))
+    }),
+    policy: optional(policyPatch)
+});
+export const createParticipantRequest = obj({
+    /** `human` is not registrable: a human uses the pairing code, not a seat the panel never waits for. */
+    role: oneOf(REGISTRABLE_ROLES),
+    displayName: str({ min: 1, max: 100 }),
+    model: optional(str({ max: 200 })),
+    /** The local pi2web agent that fills this seat. The hub wakes it; nothing polls the hub. */
+    agentId: str({ min: 1, max: 200 }),
+    tokenBudget: optional(num({ integer: true, min: 100, max: 100_000_000 }))
+});
+export const rebindParticipantRequest = obj({
+    /** Hands the seat to another local agent: the bound one died, or was picked by mistake. */
+    agentId: str({ min: 1, max: 200 }),
+    /** Filled by the human UI from the selected Agent's actual capabilities; never typed by the operator. */
+    model: optional(str({ max: 200 }))
+});
+/** Raising a spent budget is its own operation: an escalation ruling can only be used once. */
+export const participantBudgetRequest = obj({
+    tokenBudget: num({ integer: true, min: 100, max: 100_000_000 })
+});
+export const advanceRequest = obj({
+    force: withDefault(bool(), () => false),
+    reason: withDefault(str({ max: 2000 }), () => '')
+});
+export const retryWaitingRequest = obj({
+    /** Optional UI-selected subset. Busy Agents are always skipped by the hub. */
+    participantIds: optional(arr(str({ min: 1, max: 100 }), { max: 100 }))
+});
+export const resolveEscalationRequest = obj({
+    decision: str({ min: 1, max: 2000 }),
+    rationale: str({ min: 10, max: 4000 }),
+    /** Optional ruling applied to the referenced issue. `reopen` hands it back to the responder. */
+    issueDecision: optional(oneOf(['resolved', 'wontfix', 'closed', 'reopen'])),
+    extra: optional(anyJson(16 * 1024))
+});
+// ---- scoring session payloads ----
+export const nominationsRequest = obj({
+    clientRequestId: clientRequestId(),
+    nominations: arr(obj({
+        externalId: optional(str({ max: 100 })),
+        name: str({ min: 2, max: 80 }),
+        definition: str({ min: 20, max: 2000 }),
+        weightSuggestion: optional(num({ min: 0, max: 1 })),
+        anchors: optional(record(str({ min: 1, max: 400 }), { maxKeys: 20, maxKeyLength: 40 })),
+        rationale: optional(str({ max: 2000 }))
+    }), { max: 20 }),
+    nominationsComplete: withDefault(bool(), () => false),
+    usage: usage()
+});
+export const votesRequest = obj({
+    clientRequestId: clientRequestId(),
+    votes: arr(obj({
+        criterionId: str({ min: 1, max: 100 }),
+        stance: oneOf(VOTE_STANCES),
+        weight: optional(num({ min: 0, max: 1 })),
+        amendment: optional(str({ max: 1000 })),
+        rationale: optional(str({ max: 2000 }))
+    }), { min: 1, max: 40 }),
+    usage: usage()
+});
+/** Evidence is mandatory and each entry must point at a file: an unanchored score is a guess. */
+export const scoresRequest = obj({
+    clientRequestId: clientRequestId(),
+    scores: arr(obj({
+        criterionId: str({ min: 1, max: 100 }),
+        score: num({ min: 0, max: 1000 }),
+        rationale: str({ min: 20, max: 4000 }),
+        evidence: arr(evidenceItem(), { min: 1, max: 20 }),
+        confidence: optional(num({ min: 0, max: 1 })),
+        changeReason: optional(str({ max: 2000 }))
+    }), { min: 1, max: 40 }),
+    usage: usage()
+});
+export const debateArgumentRequest = obj({
+    clientRequestId: clientRequestId(),
+    stance: oneOf(DEBATE_STANCES),
+    argument: str({ min: 20, max: 4000 }),
+    evidence: withDefault(arr(evidenceItem(), { max: 20 }), () => []),
+    respondingTo: optional(str({ max: 100 })),
+    usage: usage()
+});
+/** The Pi tool submits every debate position owed by one reviewer as one logical operation. */
+export const debateArgumentsRequest = obj({
+    clientRequestId: clientRequestId(),
+    arguments: arr(obj({
+        debateId: str({ min: 1, max: 100 }),
+        stance: oneOf(DEBATE_STANCES),
+        argument: str({ min: 20, max: 4000 }),
+        evidence: withDefault(arr(evidenceItem(), { max: 20 }), () => []),
+        respondingTo: optional(str({ max: 100 }))
+    }), { min: 1, max: 40 }),
+    usage: usage()
+});
+export const finalizeRequest = obj({
+    /** Human overrides for criteria the panel could not settle, keyed by criterionId. */
+    rulings: withDefault(arr(obj({
+        criterionId: str({ min: 1, max: 100 }),
+        score: num({ min: 0, max: 1000 }),
+        rationale: str({ min: 10, max: 2000 })
+    }), { max: 40 }), () => [])
+});