@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/tools/scan-incomplete.js

@@ -0,0 +1,486 @@
+/**
+ * `gov_scan`: a deterministic scan for incomplete implementations (governance-mode 5.9).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * EVIDENCE, NEVER A VERDICT. The scan is a line-and-brace heuristic over several languages,
+ * not a parser. It returns `file:line:kind` hits plus a suspected-skeleton ratio, and
+ * NOTHING in the engine deducts GT from it: a heuristic that scores would turn every false
+ * positive (a deliberate empty `catch`, a trivial constant getter) into an unfair penalty.
+ * Reviewers, testers and the inspector cite it as evidence and still read the code.
+ *
+ * READ-ONLY AND CONFINED. Paths resolve against the working directory and are refused when
+ * the REAL path (after symlinks) leaves it; sizes, file counts and depth are bounded so a
+ * hostile or huge tree cannot stall a stage. Binary files are skipped, not decoded.
+ *
+ * The pure core, `scanText`, is exported separately so the heuristics are unit-tested on
+ * fixtures without touching a disk.
+ */
+import { promises as fs } from 'node:fs';
+import { extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { textResult } from '@aragon-agent/core';
+import { GOV_LIMITS } from '../limits.js';
+const MAX_LINE_CHARS = 400;
+const SNIPPET_CHARS = 100;
+const MAX_BODY_LINES = 60;
+const MAX_SIGNATURE_LINES = 6;
+const LOOKAHEAD_LINES = 4;
+function re(...parts) {
+    return new RegExp(parts.join(''));
+}
+/** Case-insensitive variant of `re`. */
+function rei(...parts) {
+    return new RegExp(parts.join(''), 'i');
+}
+// --- Line markers ----------------------------------------------------------
+const NOT_IMPLEMENTED = rei(String.raw `not\s+(?:yet\s+)?implemented|unimplemented|`, String.raw `\bNotImplemented(?:Error)?\b|todo!\s*\(`);
+const TODO_MARKER = /\b(?:TODO|FIXME|XXX)\b/;
+const EMPTY_CATCH_INLINE = /\bcatch\s*(?:\([^)]*\))?\s*\{\s*\}/;
+const CATCH_OPEN = /\bcatch\s*(?:\([^)]*\))?\s*\{\s*$/;
+const PY_EXCEPT = /^\s*except\b[^:]*:\s*$/;
+const PY_DEF = /^(\s*)(?:async\s+)?def\s+(\w+)\s*\(/;
+const PY_BARE = /^(?:pass|\.\.\.)$/;
+// --- Declarations in brace languages (group 1 is the name) -----------------
+const CONTROL_WORDS = new Set([
+    'if',
+    'for',
+    'while',
+    'switch',
+    'catch',
+    'return',
+    'else',
+    'with',
+    'synchronized',
+    'function',
+]);
+const BRACE_DECLARATIONS = [
+    // function foo(...)
+    re(String.raw `^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\b\s*\*?\s*(\w*)`, String.raw `\s*(?:<[^>]*>)?\s*\(`),
+    // const foo = (...) => ...
+    re(String.raw `^(?:export\s+)?(?:const|let|var)\s+(\w+)\s*(?::[^=]+)?=\s*(?:async\s*)?`, String.raw `(?:\([^)]*\)|\w+)\s*(?::[^=]+?)?\s*=>`),
+    // Rust fn, Go func
+    /^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+(\w+)/,
+    /^func\s+(?:\([^)]*\)\s*)?(\w+)/,
+    // class method: [modifiers] name(...) [: type] {
+    re(String.raw `^(?:(?:public|private|protected|static|async|override|abstract|get|set)\s+)*`, String.raw `#?(\w+)\s*(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[^{;=]+)?\s*\{`),
+    // C-like: [type] name(...) {
+    re(String.raw `^(?:[\w<>[\]*&:,?]+\s+)+(\w+)\s*\([^;]*\)\s*(?:const\s*)?`, String.raw `(?:throws\s+[\w, ]+)?\s*\{\s*$`),
+];
+/** A statement that does nothing useful: a constant return or an explicit "not done". */
+const PLACEHOLDER_STATEMENT = rei(String.raw `^(?:return\s*(?:null|undefined|nil|None|0|false|""|''|\{\s*\}|\[\s*\])?\s*;?`, String.raw `|(?:throw|raise|panic)\b.*(?:not\s*(?:yet\s+)?implemented|todo|unimplemented).*`, String.raw `|(?:unimplemented|todo)!\s*\(.*\)\s*;?)$`);
+const RETURN_STATEMENT = /^return\b/i;
+function clipSnippet(line) {
+    const flat = line.trim().replace(/\s+/g, ' ');
+    return flat.length > SNIPPET_CHARS ? `${flat.slice(0, SNIPPET_CHARS - 3)}...` : flat;
+}
+/** Drop one-line strings and `//` / block comments so braces inside them are not counted. */
+function stripForBraces(line) {
+    return line
+        .replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""')
+        .replace(/\/\*.*?\*\//g, '')
+        .replace(/\/\/.*$/, '');
+}
+function isCommentOnly(text) {
+    const t = text.trim();
+    return t.startsWith('//') || t.startsWith('#') || t.startsWith('*') || t.startsWith('/*');
+}
+// ---------------------------------------------------------------------------
+// Line-level findings
+// ---------------------------------------------------------------------------
+/**
+ * The next non-blank line, comments INCLUDED: a handler holding only a comment is a
+ * deliberate, explained swallow and is not reported as an empty catch.
+ */
+function nextNonBlankLine(lines, from) {
+    for (let i = from; i < lines.length && i < from + LOOKAHEAD_LINES; i++) {
+        const t = lines[i].trim();
+        if (t !== '')
+            return t;
+    }
+    return undefined;
+}
+/** The marker a single line carries, if any. Priority: not_implemented, todo, empty catch. */
+function lineKind(lines, index) {
+    const line = lines[index];
+    if (NOT_IMPLEMENTED.test(line))
+        return 'not_implemented';
+    if (TODO_MARKER.test(line))
+        return 'todo';
+    if (EMPTY_CATCH_INLINE.test(line))
+        return 'empty_catch';
+    if (CATCH_OPEN.test(line) && nextNonBlankLine(lines, index + 1) === '}')
+        return 'empty_catch';
+    if (PY_EXCEPT.test(line) && nextNonBlankLine(lines, index + 1) === 'pass')
+        return 'empty_catch';
+    return null;
+}
+const NOT_A_SKELETON = { skeleton: false, kind: null };
+const TRIPLE_QUOTE = /("""|''')/;
+const DOCSTRING_START = /^[rbuRBU]*("""|''')/;
+function indentOf(raw) {
+    return raw.length - raw.trimStart().length;
+}
+/** Index of the first body line: the line after the (possibly wrapped) signature's `:`. */
+function pythonBodyStart(lines, index) {
+    const last = Math.min(lines.length, index + MAX_SIGNATURE_LINES);
+    for (let i = index; i < last; i++) {
+        if (/:\s*(?:#.*)?$/.test(lines[i]))
+            return i + 1;
+    }
+    return -1;
+}
+/** The statements of a Python body: comments and a leading docstring are dropped. */
+function pythonBodyStatements(lines, start, indent) {
+    const statements = [];
+    let inDocstring = false;
+    const end = Math.min(lines.length, start + MAX_BODY_LINES);
+    for (let i = start; i < end; i++) {
+        const raw = lines[i];
+        const t = raw.trim();
+        if (t === '')
+            continue;
+        if (!inDocstring && indentOf(raw) <= indent)
+            break;
+        const quote = TRIPLE_QUOTE.exec(t)?.[1];
+        if (inDocstring) {
+            if (quote)
+                inDocstring = false;
+        }
+        else if (quote && DOCSTRING_START.test(t)) {
+            inDocstring = t.indexOf(quote) === t.lastIndexOf(quote);
+        }
+        else if (!t.startsWith('#')) {
+            statements.push(t);
+        }
+    }
+    return statements;
+}
+/** Python: the body is the more-indented block after the (possibly wrapped) signature. */
+function pythonFunction(lines, index) {
+    const m = PY_DEF.exec(lines[index]);
+    if (!m)
+        return null;
+    const start = pythonBodyStart(lines, index);
+    if (start < 0)
+        return NOT_A_SKELETON;
+    const statements = pythonBodyStatements(lines, start, m[1].length);
+    const bare = statements.every((s) => PY_BARE.test(s));
+    const placeholders = statements.every((s) => PY_BARE.test(s) || PLACEHOLDER_STATEMENT.test(s));
+    if (!placeholders)
+        return NOT_A_SKELETON;
+    if (bare)
+        return { skeleton: true, kind: 'bare_pass' };
+    const constantReturn = statements.some((s) => RETURN_STATEMENT.test(s));
+    return { skeleton: true, kind: constantReturn ? 'placeholder_return' : null };
+}
+/** The declaration name if `line` opens a brace-language function; else `null`. */
+function braceDeclaration(line) {
+    const t = line.trim();
+    for (const pattern of BRACE_DECLARATIONS) {
+        const m = pattern.exec(t);
+        if (!m)
+            continue;
+        const name = m[1] ?? '';
+        return CONTROL_WORDS.has(name) ? null : name || 'function';
+    }
+    return null;
+}
+/**
+ * Feed one (already stripped) line through the brace counter. Returns the text after the
+ * body's opening brace, and whether the closing brace was reached on this line.
+ */
+function consumeBraceLine(code, state) {
+    let segment = '';
+    for (const ch of code) {
+        if (ch === '{') {
+            state.depth++;
+            if (!state.started) {
+                state.started = true;
+                segment = '';
+                continue;
+            }
+        }
+        else if (ch === '}') {
+            state.depth--;
+            if (state.started && state.depth === 0)
+                return { segment: segment.trim(), closed: true };
+        }
+        if (state.started)
+            segment += ch;
+    }
+    return { segment: segment.trim(), closed: false };
+}
+/** The statements between the first `{` at/after `index` and its closing brace. */
+function braceBody(lines, index) {
+    const state = { depth: 0, started: false };
+    const statements = [];
+    const last = Math.min(lines.length, index + MAX_BODY_LINES);
+    for (let i = index; i < last; i++) {
+        if (!state.started && i > index + MAX_SIGNATURE_LINES)
+            return null;
+        const { segment, closed } = consumeBraceLine(stripForBraces(lines[i]), state);
+        if (segment !== '' && (closed || !isCommentOnly(segment)))
+            statements.push(segment);
+        if (closed) {
+            const hasTodo = lines.slice(index, i + 1).some((l) => TODO_MARKER.test(l));
+            return { statements, hasTodo };
+        }
+    }
+    return null;
+}
+/** An arrow declaration whose body is an expression, not a block. */
+function arrowExpressionBody(line) {
+    const m = /=>\s*(\S.*)$/.exec(line);
+    return m && !m[1].startsWith('{') ? m[1].replace(/;+\s*$/, '').trim() : null;
+}
+function braceFunction(lines, index) {
+    const line = lines[index];
+    if (braceDeclaration(line) === null)
+        return null;
+    const expression = arrowExpressionBody(line);
+    if (expression !== null) {
+        const isNothing = /^(?:null|undefined)$/.test(expression);
+        return { skeleton: isNothing, kind: isNothing ? 'placeholder_return' : null };
+    }
+    const body = braceBody(lines, index);
+    if (body === null)
+        return NOT_A_SKELETON;
+    const statements = body.statements.map((s) => s.replace(/;+\s*$/, '').trim()).filter(Boolean);
+    const skeleton = statements.length === 0
+        ? body.hasTodo
+        : statements.every((s) => PLACEHOLDER_STATEMENT.test(s));
+    const constantReturn = statements.some((s) => RETURN_STATEMENT.test(s));
+    return { skeleton, kind: skeleton && constantReturn ? 'placeholder_return' : null };
+}
+// ---------------------------------------------------------------------------
+// scanText
+// ---------------------------------------------------------------------------
+/**
+ * Scan one file's text. Pure and deterministic: the same input always yields the same hits,
+ * in ascending line order, at most one per line and kind.
+ */
+export function scanText(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => (l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) : l));
+    const found = new Map();
+    const add = (index, kind) => {
+        const key = `${index}:${kind}`;
+        if (found.has(key))
+            return;
+        found.set(key, { line: index + 1, kind, text: clipSnippet(lines[index]) });
+    };
+    let functions = 0;
+    let skeletonFunctions = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const kind = lineKind(lines, index);
+        if (kind)
+            add(index, kind);
+        const fn = pythonFunction(lines, index) ?? braceFunction(lines, index);
+        if (!fn)
+            continue;
+        functions++;
+        if (!fn.skeleton)
+            continue;
+        skeletonFunctions++;
+        if (fn.kind)
+            add(index, fn.kind);
+    }
+    const findings = [...found.values()].sort((a, b) => a.line - b.line || a.kind.localeCompare(b.kind));
+    return { findings, functions, skeletonFunctions };
+}
+const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
+const DEFAULT_MAX_FILES = 200;
+const MAX_WALK_DEPTH = 6;
+const BINARY_PROBE_BYTES = 4096;
+const SKIP_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.next',
+    'target',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.cache',
+]);
+const CODE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.kt',
+    '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.rb', '.php', '.swift', '.scala', '.lua', '.sh',
+]);
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function displayPath(state, real) {
+    return relative(state.root, real).replace(/\\/g, '/') || '.';
+}
+async function scanFile(state, real, size) {
+    const shown = displayPath(state, real);
+    if (size > state.maxBytes) {
+        state.report.skipped.push({ path: shown, reason: `larger than ${state.maxBytes} bytes` });
+        return;
+    }
+    const buffer = await fs.readFile(real);
+    if (buffer.subarray(0, BINARY_PROBE_BYTES).includes(0)) {
+        state.report.skipped.push({ path: shown, reason: 'binary file' });
+        return;
+    }
+    const scan = scanText(buffer.toString('utf8'));
+    state.report.files++;
+    state.report.functions += scan.functions;
+    state.report.skeletonFunctions += scan.skeletonFunctions;
+    for (const f of scan.findings)
+        state.report.findings.push({ ...f, file: shown });
+}
+async function walkDirectory(state, dir, depth) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (state.report.files >= state.maxFiles) {
+            state.report.truncated = true;
+            return;
+        }
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const descend = depth < MAX_WALK_DEPTH && !SKIP_DIRECTORIES.has(entry.name);
+            if (descend)
+                await walkDirectory(state, full, depth + 1);
+        }
+        else if (entry.isFile() && CODE_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+            await visit(state, full, depth);
+        }
+    }
+}
+/** Scan one path (file or directory) once; refuses anything whose real path leaves the root. */
+async function visit(state, raw, depth) {
+    let real;
+    try {
+        real = await fs.realpath(resolve(state.root, raw));
+    }
+    catch {
+        state.report.skipped.push({ path: raw, reason: 'not found' });
+        return;
+    }
+    if (!isInside(state.root, real)) {
+        state.report.skipped.push({ path: raw, reason: 'outside the working directory' });
+        return;
+    }
+    if (state.seen.has(real))
+        return;
+    state.seen.add(real);
+    const stat = await fs.stat(real);
+    if (stat.isDirectory())
+        return walkDirectory(state, real, depth);
+    if (!stat.isFile())
+        return;
+    if (state.report.files >= state.maxFiles) {
+        state.report.truncated = true;
+        return;
+    }
+    await scanFile(state, real, stat.size);
+}
+/**
+ * Scan files and directories under `cwd`. Directories are walked (bounded depth, known code
+ * extensions, build and vendor trees skipped); explicit files are scanned whatever their
+ * extension. Only the first `GOV_LIMITS.scanPathsMax` paths are used; the rest are counted
+ * as truncation.
+ */
+export async function scanPaths(options) {
+    const report = {
+        files: 0,
+        findings: [],
+        skipped: [],
+        functions: 0,
+        skeletonFunctions: 0,
+        skeletonRatio: 0,
+        truncated: false,
+    };
+    const state = {
+        root: await fs.realpath(resolve(options.cwd)),
+        maxBytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+        maxFiles: options.maxFiles ?? DEFAULT_MAX_FILES,
+        seen: new Set(),
+        report,
+    };
+    const unique = [...new Set(options.paths.map((p) => p.trim()).filter((p) => p !== ''))];
+    if (unique.length > GOV_LIMITS.scanPathsMax)
+        report.truncated = true;
+    for (const p of unique.slice(0, GOV_LIMITS.scanPathsMax))
+        await visit(state, p, 0);
+    report.skeletonRatio = report.functions === 0 ? 0 : report.skeletonFunctions / report.functions;
+    return report;
+}
+// ---------------------------------------------------------------------------
+// Output and the tool
+// ---------------------------------------------------------------------------
+const MAX_FINDINGS_SHOWN = 80;
+const MAX_SKIPPED_SHOWN = 10;
+/** The text the model reads. The first line is `OK:` (7.1 rule 2). */
+export function formatScanReport(report) {
+    const lines = [
+        `OK: scanned ${report.files} file(s): ${report.functions} function(s), ` +
+            `${report.skeletonFunctions} suspected skeleton, ` +
+            `skeletonRatio ${report.skeletonRatio.toFixed(2)}.`,
+    ];
+    for (const f of report.findings.slice(0, MAX_FINDINGS_SHOWN)) {
+        lines.push(`${f.file}:${f.line}:${f.kind}  ${f.text}`);
+    }
+    if (report.findings.length > MAX_FINDINGS_SHOWN) {
+        lines.push(`(${report.findings.length - MAX_FINDINGS_SHOWN} more hits not shown)`);
+    }
+    for (const s of report.skipped.slice(0, MAX_SKIPPED_SHOWN)) {
+        lines.push(`SKIPPED ${s.path}: ${s.reason}`);
+    }
+    if (report.skipped.length > MAX_SKIPPED_SHOWN) {
+        lines.push(`(${report.skipped.length - MAX_SKIPPED_SHOWN} more skipped paths not shown)`);
+    }
+    if (report.truncated) {
+        lines.push(`TRUNCATED: the scan stopped at its file or path cap.`);
+    }
+    lines.push(`A skeletonRatio above ${GOV_LIMITS.skeletonRatioThreshold} marks a skeleton submission. ` +
+        'This scan is heuristic evidence only: confirm each hit by reading the code.');
+    return lines.join('\n');
+}
+function pathsFrom(raw) {
+    const value = raw !== null && typeof raw === 'object' ? raw.paths : undefined;
+    if (typeof value === 'string')
+        return value.split(/\r?\n/);
+    return Array.isArray(value) ? value.filter((p) => typeof p === 'string') : [];
+}
+/** `gov_scan`: REV, TEST and INSP. Read-only. */
+export function makeScanTool(ctx) {
+    return {
+        name: 'gov_scan',
+        label: 'Scan for incomplete work',
+        description: 'Scan files or directories for incomplete implementations: TODO/FIXME/XXX, "not ' +
+            'implemented", empty catch blocks, bodies that are only pass or "...", and functions ' +
+            'that only return a placeholder. Returns file:line:kind hits and a skeletonRatio. ' +
+            `Paths are relative to the working directory (at most ${GOV_LIMITS.scanPathsMax}; ` +
+            'paths outside it are refused). Heuristic evidence only: it never scores anyone.',
+        parameters: {
+            type: 'object',
+            properties: {
+                paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Files or directories to scan.',
+                },
+            },
+            required: ['paths'],
+        },
+        async execute(_id, params) {
+            const paths = pathsFrom(params)
+                .map((p) => p.trim())
+                .filter((p) => p !== '');
+            if (paths.length === 0) {
+                return textResult('NOT ACCEPTED: gov_scan needs paths: a list of files or directories.');
+            }
+            return textResult(formatScanReport(await scanPaths({ cwd: ctx.getCwd(), paths })));
+        },
+    };
+}

package/dist/governance/tools/shared-tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tools every governed child can call: `ledger_standings`, `gov_read`, `gov_view`
+ * (governance-mode 7.3, 8.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THESE THREE ARE THE ONLY WINDOWS ONTO GOVERNANCE STATE. A child has no file path to the
+ * governance store (and the read tripwire refuses calls that mention it, D-6); everything it
+ * may know about other agents arrives through `gov_read`, which the engine answers from the
+ * ONE visibility matrix, and `gov_view`, which the engine answers from a deterministic
+ * policy (D-9) and logs either way. The tools here only shape and validate the request; the
+ * decision about what a role may see is never made in this layer.
+ *
+ * Both request tools are identity-bound by their factories: the model cannot ask "as" a
+ * different agent.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { GovernanceEngineApi, Identity } from '../types.js';
+import { type Normalized } from './normalize-util.js';
+/** What `gov_read` asks the engine for: a listing, or one artifact page. */
+export interface ReadRequest {
+    list?: true;
+    id?: string;
+    offset?: number;
+}
+export interface ViewRequest {
+    target: string;
+    reason: string;
+}
+/**
+ * Validate a `gov_read` request. Pure.
+ *
+ * Repairs: no `id` and no `list` becomes a listing (the useful default); both given means
+ * the `id` wins; a negative `offset` becomes 0.
+ */
+export declare function normalizeReadRequest(raw: unknown): Normalized<ReadRequest>;
+/** Validate a `gov_view` request. Pure. The reason must say WHY, not merely exist. */
+export declare function normalizeViewRequest(raw: unknown): Normalized<ViewRequest>;
+/** `ledger_standings`: the public scoreboard. Takes no arguments. */
+export declare function makeStandingsTool(engine: GovernanceEngineApi): AgentTool;
+/** `gov_read`: artifacts this role may see, paged. Visibility is the engine's decision. */
+export declare function makeReadTool(engine: GovernanceEngineApi, identity: Identity): AgentTool;
+/** `gov_view`: ask to see something outside the default matrix. Decided by fixed policy. */
+export declare function makeViewTool(engine: GovernanceEngineApi, identity: Identity): AgentTool;

package/dist/governance/tools/shared-tools.js

@@ -0,0 +1,125 @@
+/**
+ * Tools every governed child can call: `ledger_standings`, `gov_read`, `gov_view`
+ * (governance-mode 7.3, 8.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THESE THREE ARE THE ONLY WINDOWS ONTO GOVERNANCE STATE. A child has no file path to the
+ * governance store (and the read tripwire refuses calls that mention it, D-6); everything it
+ * may know about other agents arrives through `gov_read`, which the engine answers from the
+ * ONE visibility matrix, and `gov_view`, which the engine answers from a deterministic
+ * policy (D-9) and logs either way. The tools here only shape and validate the request; the
+ * decision about what a role may see is never made in this layer.
+ *
+ * Both request tools are identity-bound by their factories: the model cannot ask "as" a
+ * different agent.
+ */
+import { textResult } from '@aragon-agent/core';
+import { GOV_LIMITS } from '../limits.js';
+import { Issues, formatNotAccepted, isRecord, readBool, readInteger, withNotes, } from './normalize-util.js';
+const ARTIFACT_ID_CHARS = 120;
+const VIEW_TARGET_CHARS = 200;
+const VIEW_REASON_CHARS = 600;
+/**
+ * Validate a `gov_read` request. Pure.
+ *
+ * Repairs: no `id` and no `list` becomes a listing (the useful default); both given means
+ * the `id` wins; a negative `offset` becomes 0.
+ */
+export function normalizeReadRequest(raw) {
+    const issues = new Issues();
+    const args = isRecord(raw) ? raw : {};
+    const id = issues.str(args.id, 'id', 400);
+    if (id.length > ARTIFACT_ID_CHARS) {
+        issues.fail(`id is not an artifact id (at most ${ARTIFACT_ID_CHARS} chars); use list.`);
+    }
+    const wantsList = readBool(args.list) === true;
+    const offset = readInteger(args.offset);
+    if (args.offset !== undefined && offset === undefined) {
+        issues.fail('offset must be a non-negative integer.');
+    }
+    if (id !== '' && wantsList)
+        issues.note('both id and list were given; reading the id.');
+    if (id === '' && !wantsList)
+        issues.note('neither id nor list was given; listing artifacts.');
+    if (offset !== undefined && offset < 0)
+        issues.note('offset was negative; using 0.');
+    const request = id !== ''
+        ? { id, ...(offset !== undefined ? { offset: Math.max(0, offset) } : {}) }
+        : { list: true };
+    return issues.result(request);
+}
+/** Validate a `gov_view` request. Pure. The reason must say WHY, not merely exist. */
+export function normalizeViewRequest(raw) {
+    const issues = new Issues();
+    const args = isRecord(raw) ? raw : {};
+    const target = issues.str(args.target, 'target', VIEW_TARGET_CHARS, true);
+    const reason = issues.str(args.reason, 'reason', VIEW_REASON_CHARS, true);
+    if (reason !== '' && reason.length < GOV_LIMITS.viewReasonMinChars) {
+        issues.fail(`reason must explain why you need it, at least ${GOV_LIMITS.viewReasonMinChars} ` +
+            `characters (got ${reason.length}).`);
+    }
+    return issues.result({ target, reason });
+}
+function runRequest(tool, normalized, forward) {
+    if (!normalized.ok)
+        return textResult(formatNotAccepted(tool, normalized.errors));
+    return textResult(withNotes(forward(normalized.value), normalized.notes));
+}
+/** `ledger_standings`: the public scoreboard. Takes no arguments. */
+export function makeStandingsTool(engine) {
+    return {
+        name: 'ledger_standings',
+        label: 'GT standings',
+        description: 'Show the public GT standings of the run: every scored agent with confirmed GT, ' +
+            'escrowed GT (P), standing label and team health. Read-only.',
+        parameters: { type: 'object', properties: {} },
+        async execute() {
+            return textResult(engine.standings());
+        },
+    };
+}
+/** `gov_read`: artifacts this role may see, paged. Visibility is the engine's decision. */
+export function makeReadTool(engine, identity) {
+    return {
+        name: 'gov_read',
+        label: 'Read governed artifact',
+        description: 'Read material from the governed run that your role may see. Call with list:true to ' +
+            'see the artifact ids you can read, then with id (and offset for the next page; a ' +
+            `page is about ${GOV_LIMITS.readPageChars} characters). A request for something your ` +
+            'role may not see is answered with NOT ACCEPTED and is logged.',
+        parameters: {
+            type: 'object',
+            properties: {
+                list: { type: 'boolean', description: 'List the artifacts you may read.' },
+                id: { type: 'string', description: 'Artifact id from the list.' },
+                offset: { type: 'number', description: 'Character offset of the page to read.' },
+            },
+        },
+        async execute(_id, params) {
+            return runRequest('gov_read', normalizeReadRequest(params), (request) => engine.readArtifact(identity, request));
+        },
+    };
+}
+/** `gov_view`: ask to see something outside the default matrix. Decided by fixed policy. */
+export function makeViewTool(engine, identity) {
+    return {
+        name: 'gov_view',
+        label: 'Request a view',
+        description: 'Ask to see material outside your default view. target names what you want; reason ' +
+            `(at least ${GOV_LIMITS.viewReasonMinChars} characters) says why you need it. A fixed ` +
+            `policy decides; you get ${GOV_LIMITS.viewRequestsPerChild} request(s) and every ` +
+            'request is logged for the Inspector.',
+        parameters: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'What you want to see.' },
+                reason: { type: 'string', description: 'Why you need it.' },
+            },
+            required: ['target', 'reason'],
+        },
+        async execute(_id, params) {
+            return runRequest('gov_view', normalizeViewRequest(params), (request) => engine.requestView(identity, request));
+        },
+    };
+}

package/dist/governance/tools/submit-normalizers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Normalizers for `gov_submit_work` / `gov_submit_review` / `gov_submit_test`
+ * (governance-mode 5.9, 7.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock.
+ *
+ * THE OUTPUT IS BUILT FROM KNOWN FIELDS ONLY. Each normalizer copies the keys it knows into
+ * a fresh object, so an `agentId` (or any other key) in the arguments can never reach the
+ * engine: identity is closed over by the tool factory, not argued by the model (5.9).
+ *
+ * EXPORTED FOR THE ENGINE. A submission that arrives by another path (resume, replay, a
+ * future REST surface) is validated by the same functions and gets the same verdict.
+ *
+ * CONTRADICTIONS ARE REJECTED, NOT GUESSED (D-15). A `PASS` verdict next to a blocker
+ * finding, or an `ALL_PASS` next to a `gap` row, is not repairable: either the verdict or
+ * the evidence is wrong and only the author knows which.
+ */
+import type { ReviewSubmission, TestSubmission, WorkSubmission } from '../types.js';
+import { type Normalized } from './normalize-util.js';
+export type WorkSubmissionInput = Pick<WorkSubmission, 'wpId' | 'summary' | 'filesChanged' | 'interfaceContracts' | 'verification'> & Partial<Pick<WorkSubmission, 'appeal' | 'escalate'>>;
+/** Validate and repair a `gov_submit_work` argument object. Pure. */
+export declare function normalizeWorkSubmission(raw: unknown): Normalized<WorkSubmissionInput>;
+export type ReviewSubmissionInput = Pick<ReviewSubmission, 'wpId' | 'verdict' | 'checklist' | 'findings' | 'fixesApplied' | 'integrationAssessment' | 'appealResponses' | 'requiredChanges'> & Partial<Pick<ReviewSubmission, 'excellence' | 'securityFinding'>>;
+/** Validate and repair a `gov_submit_review` argument object. Pure. */
+export declare function normalizeReviewSubmission(raw: unknown): Normalized<ReviewSubmissionInput>;
+export type TestSubmissionInput = Pick<TestSubmission, 'wpId' | 'verdict' | 'traceability' | 'commands' | 'issues' | 'boundaryTestsWritten' | 'claims'> & Partial<Pick<TestSubmission, 'skeletonRatio' | 'skeletonEvidence'>>;
+/** Validate and repair a `gov_submit_test` argument object. Pure. */
+export declare function normalizeTestSubmission(raw: unknown): Normalized<TestSubmissionInput>;