@enderfga/claw-orchestrator 5.0.0 → 6.0.0

package/dist/src/verify/baseline.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Baseline capture — the primitive nothing in this repo had.
+ *
+ * Two existing call sites tried to answer "what did this run change" and both
+ * get it wrong in a way that matters:
+ *
+ *  - `council.ts` diffs `HEAD~20..HEAD` (with a `HEAD~10` fallback), a hardcoded
+ *    magic window that silently returns nothing on shallow history and has no
+ *    relationship to when the run actually started.
+ *  - `autoloop/dispatcher.ts` runs a bare `git diff`, which lists tracked
+ *    modifications only. Files the Coder *created* appear in neither the patch
+ *    nor the `--name-only` fallback, yet the following `git add -A` commits them.
+ *    So the Reviewer audits a diff that structurally cannot show new files.
+ *
+ * Here the base commit is recorded when the run starts, and the change set is
+ * tracked-diff ∪ untracked-files. Nothing mutates the caller's index: untracked
+ * files are rendered with `git diff --no-index /dev/null <file>`, which emits a
+ * proper new-file patch without an `add -N`.
+ */
+export type ChangeStatus = 'added' | 'modified' | 'deleted' | 'untracked';
+export interface ChangedFile {
+    path: string;
+    status: ChangeStatus;
+    insertions: number;
+    deletions: number;
+}
+/** `git rev-parse HEAD`, or undefined when cwd is not a repo (or has no commits yet). */
+export declare function captureBaseline(cwd: string): Promise<string | undefined>;
+/**
+ * Everything the run touched since `baseSha`: tracked changes in the working
+ * tree (committed or not) plus every untracked file.
+ */
+export declare function changedFilesSince(cwd: string, baseSha: string | undefined): Promise<ChangedFile[]>;
+/**
+ * A unified patch covering the same set: `git diff <base>` for tracked changes,
+ * then a synthetic new-file patch per untracked file appended after it.
+ */
+export declare function capturePatch(cwd: string, baseSha: string | undefined): Promise<string>;
+/**
+ * A digest of the working tree's current *content*.
+ *
+ * Evidence describes the tree as it was when the checks ran. If anything moves
+ * afterwards the bundle still exists but no longer describes what is there, and
+ * a run that keeps reporting `verified` on the strength of it is claiming
+ * something nobody measured. Comparing this before and after is how the kernel
+ * notices.
+ *
+ * The first version of this hashed `git rev-parse HEAD` plus
+ * `git status --porcelain`, which does not work: porcelain reports a file's
+ * *state*, not its bytes. A file that was already `M` before the verifier and
+ * is rewritten afterwards still prints ` M a.txt`, so the digest was unchanged
+ * and a stale verdict sailed through. The common case — an agent editing a file
+ * it had already edited — was exactly the case it missed.
+ *
+ * So this hashes content: HEAD, the full `git diff HEAD` patch (which covers
+ * staged and unstaged changes to tracked files), and the path plus bytes of
+ * every untracked file.
+ *
+ * Returns undefined outside a repo — a caller that cannot fingerprint must not
+ * assume the tree held still.
+ */
+export declare function treeFingerprint(cwd: string): Promise<string | undefined>;
+/**
+ * True when `file` sits under `prefix`.
+ *
+ * Segment-aware, so `srcfoo/a.ts` is not under `src`. `.` and `''` both mean the
+ * repo root and match everything — without that, a policy of `requirePaths: ['.']`
+ * ("the run must change something") reports that nothing changed no matter what
+ * the run did.
+ */
+export declare function isUnder(file: string, prefix: string): boolean;
+/** Resolve a check-relative path against the run cwd. */
+export declare function resolveIn(cwd: string, p: string): string;

package/dist/src/verify/baseline.js

@@ -0,0 +1,186 @@
+/**
+ * Baseline capture — the primitive nothing in this repo had.
+ *
+ * Two existing call sites tried to answer "what did this run change" and both
+ * get it wrong in a way that matters:
+ *
+ *  - `council.ts` diffs `HEAD~20..HEAD` (with a `HEAD~10` fallback), a hardcoded
+ *    magic window that silently returns nothing on shallow history and has no
+ *    relationship to when the run actually started.
+ *  - `autoloop/dispatcher.ts` runs a bare `git diff`, which lists tracked
+ *    modifications only. Files the Coder *created* appear in neither the patch
+ *    nor the `--name-only` fallback, yet the following `git add -A` commits them.
+ *    So the Reviewer audits a diff that structurally cannot show new files.
+ *
+ * Here the base commit is recorded when the run starts, and the change set is
+ * tracked-diff ∪ untracked-files. Nothing mutates the caller's index: untracked
+ * files are rendered with `git diff --no-index /dev/null <file>`, which emits a
+ * proper new-file patch without an `add -N`.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { exec } from '../kernel/exec.js';
+const GIT_TIMEOUT_MS = 60_000;
+/** `git rev-parse HEAD`, or undefined when cwd is not a repo (or has no commits yet). */
+export async function captureBaseline(cwd) {
+    const r = await exec('git', ['-C', cwd, 'rev-parse', 'HEAD'], { timeoutMs: GIT_TIMEOUT_MS });
+    if (r.code !== 0)
+        return undefined;
+    const sha = r.out.trim();
+    return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : undefined;
+}
+async function untrackedFiles(cwd) {
+    const r = await exec('git', ['-C', cwd, 'ls-files', '--others', '--exclude-standard'], {
+        timeoutMs: GIT_TIMEOUT_MS,
+    });
+    if (r.code !== 0)
+        return [];
+    return r.out
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+async function countLines(cwd, file) {
+    const r = await exec('git', ['-C', cwd, 'diff', '--no-index', '--numstat', '/dev/null', file], {
+        timeoutMs: GIT_TIMEOUT_MS,
+    });
+    // `--no-index` exits 1 when there are differences, which is the normal case here.
+    const first = r.out.split('\n').find((l) => l.trim() !== '');
+    if (!first)
+        return 0;
+    const n = Number(first.split('\t')[0]);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * Everything the run touched since `baseSha`: tracked changes in the working
+ * tree (committed or not) plus every untracked file.
+ */
+export async function changedFilesSince(cwd, baseSha) {
+    const files = [];
+    if (baseSha) {
+        const r = await exec('git', ['-C', cwd, 'diff', '--numstat', '--no-renames', baseSha, '--'], {
+            timeoutMs: GIT_TIMEOUT_MS,
+        });
+        if (r.code === 0) {
+            for (const line of r.out.split('\n')) {
+                const parts = line.split('\t');
+                if (parts.length < 3)
+                    continue;
+                const insertions = Number(parts[0]);
+                const deletions = Number(parts[1]);
+                const file = parts.slice(2).join('\t').trim();
+                if (!file)
+                    continue;
+                // A binary file reports "-\t-"; count it as touched with zero line deltas.
+                files.push({
+                    path: file,
+                    status: deletions > 0 && insertions === 0 ? 'deleted' : 'modified',
+                    insertions: Number.isFinite(insertions) ? insertions : 0,
+                    deletions: Number.isFinite(deletions) ? deletions : 0,
+                });
+            }
+        }
+    }
+    const seen = new Set(files.map((f) => f.path));
+    for (const file of await untrackedFiles(cwd)) {
+        if (seen.has(file))
+            continue;
+        files.push({ path: file, status: 'untracked', insertions: await countLines(cwd, file), deletions: 0 });
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * A unified patch covering the same set: `git diff <base>` for tracked changes,
+ * then a synthetic new-file patch per untracked file appended after it.
+ */
+export async function capturePatch(cwd, baseSha) {
+    const parts = [];
+    if (baseSha) {
+        const r = await exec('git', ['-C', cwd, 'diff', '--unified=3', '--no-renames', baseSha, '--'], {
+            timeoutMs: GIT_TIMEOUT_MS,
+        });
+        if (r.code === 0 && r.out.trim())
+            parts.push(r.out.replace(/\n*$/, '\n'));
+    }
+    for (const file of await untrackedFiles(cwd)) {
+        const r = await exec('git', ['-C', cwd, 'diff', '--no-index', '--unified=3', '/dev/null', file], {
+            cwd,
+            timeoutMs: GIT_TIMEOUT_MS,
+        });
+        // Exit 1 = "differences found", the expected outcome for a new file.
+        if ((r.code === 0 || r.code === 1) && r.out.trim())
+            parts.push(r.out.replace(/\n*$/, '\n'));
+    }
+    return parts.join('');
+}
+/**
+ * A digest of the working tree's current *content*.
+ *
+ * Evidence describes the tree as it was when the checks ran. If anything moves
+ * afterwards the bundle still exists but no longer describes what is there, and
+ * a run that keeps reporting `verified` on the strength of it is claiming
+ * something nobody measured. Comparing this before and after is how the kernel
+ * notices.
+ *
+ * The first version of this hashed `git rev-parse HEAD` plus
+ * `git status --porcelain`, which does not work: porcelain reports a file's
+ * *state*, not its bytes. A file that was already `M` before the verifier and
+ * is rewritten afterwards still prints ` M a.txt`, so the digest was unchanged
+ * and a stale verdict sailed through. The common case — an agent editing a file
+ * it had already edited — was exactly the case it missed.
+ *
+ * So this hashes content: HEAD, the full `git diff HEAD` patch (which covers
+ * staged and unstaged changes to tracked files), and the path plus bytes of
+ * every untracked file.
+ *
+ * Returns undefined outside a repo — a caller that cannot fingerprint must not
+ * assume the tree held still.
+ */
+export async function treeFingerprint(cwd) {
+    const status = await exec('git', ['-C', cwd, 'status', '--porcelain'], { timeoutMs: GIT_TIMEOUT_MS });
+    if (status.code !== 0)
+        return undefined;
+    const head = await exec('git', ['-C', cwd, 'rev-parse', 'HEAD'], { timeoutMs: GIT_TIMEOUT_MS });
+    const tracked = await exec('git', ['-C', cwd, 'diff', 'HEAD'], { timeoutMs: GIT_TIMEOUT_MS });
+    const hash = crypto.createHash('sha256');
+    hash.update(head.code === 0 ? head.out.trim() : 'no-head');
+    hash.update('\u0000');
+    hash.update(tracked.code === 0 ? tracked.out : status.out);
+    // Untracked files are invisible to `git diff`, so hash them by hand — path and
+    // bytes both, so a rename and an edit are each detected.
+    for (const file of (await untrackedFiles(cwd)).sort()) {
+        hash.update('\u0000');
+        hash.update(file);
+        try {
+            hash.update(fs.readFileSync(path.join(cwd, file)));
+        }
+        catch {
+            // Unreadable (a dangling symlink, a race with a delete): record that we
+            // could not read it rather than silently treating it as empty.
+            hash.update('\u0000unreadable');
+        }
+    }
+    return hash.digest('hex');
+}
+/**
+ * True when `file` sits under `prefix`.
+ *
+ * Segment-aware, so `srcfoo/a.ts` is not under `src`. `.` and `''` both mean the
+ * repo root and match everything — without that, a policy of `requirePaths: ['.']`
+ * ("the run must change something") reports that nothing changed no matter what
+ * the run did.
+ */
+export function isUnder(file, prefix) {
+    const norm = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '').replace(/^\.$/, '');
+    const f = norm(file);
+    const p = norm(prefix);
+    if (p === '')
+        return true;
+    return f === p || f.startsWith(p + '/');
+}
+/** Resolve a check-relative path against the run cwd. */
+export function resolveIn(cwd, p) {
+    return path.isAbsolute(p) ? p : path.join(cwd, p);
+}
+//# sourceMappingURL=baseline.js.map

package/dist/src/verify/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../../src/verify/baseline.ts"],"names":[],"mappings":"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"}

package/dist/src/verify/contract.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Acceptance contracts — what the runtime itself checks before calling a run done.
+ *
+ * Every completion signal that existed before this module was the agent grading
+ * its own work: council terminated on a regex over agent prose (`consensus.ts`),
+ * autoloop's `eval_output` was whatever the Coder passed to a tool call
+ * (`autoloop/agent-tools.ts`), ultraapp's frontend gate was a sentence in a
+ * persona string (`ultraapp/council-adapter.ts`). A contract is the opposite:
+ * a caller-declared list of checks that *we* execute and whose exit codes we read.
+ *
+ * Provenance rule, and the reason `normalizeContract` exists: a contract may
+ * come from the caller or from a mode default, never from agent output. If an
+ * agent could declare its own checks we would be back to self-grading with extra
+ * steps. Nothing in the kernel reads a contract out of a node's result.
+ */
+/** Argv form only — there is no shell string anywhere, so there is nothing to inject into. */
+export interface CommandCheck {
+    type: 'command';
+    cmd: string;
+    args?: string[];
+    /** Relative to the run cwd when not absolute. */
+    cwd?: string;
+    timeoutMs?: number;
+    /** Exit code that counts as pass. Default 0. */
+    expectExit?: number;
+}
+export interface HttpCheck {
+    type: 'http';
+    url: string;
+    /** Default 200. */
+    expectStatus?: number;
+    /** Total time to keep retrying before failing. Default 30s. */
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+/**
+ * Captures and stores a screenshot; it does not judge pixels. The judgement is
+ * still a human's or an agent's, but whether the capture actually happened is
+ * now decided by the runtime instead of by an agent's self-report. Do not
+ * describe this as visual regression — it is evidence collection.
+ */
+export interface ScreenshotCheck {
+    type: 'screenshot';
+    url: string;
+    viewports: Array<{
+        width: number;
+        height: number;
+        label?: string;
+    }>;
+    /** Chrome/Chromium binary; resolved from the usual locations when omitted. */
+    browserBin?: string;
+    timeoutMs?: number;
+}
+export interface DiffPolicyCheck {
+    type: 'diff_policy';
+    maxFiles?: number;
+    /** Glob-ish prefixes that must not be touched. */
+    forbidPaths?: string[];
+    /** At least one changed file must sit under one of these. */
+    requirePaths?: string[];
+}
+export interface FileCheck {
+    type: 'file';
+    path: string;
+    /** Default true. `false` asserts absence. */
+    exists?: boolean;
+    /** Applied to file contents when present. */
+    matches?: string;
+}
+export type CheckSpec = CommandCheck | HttpCheck | ScreenshotCheck | DiffPolicyCheck | FileCheck;
+export interface ContractCheck {
+    /** Stable id used in the evidence bundle. Generated when omitted. */
+    id?: string;
+    spec: CheckSpec;
+    /**
+     * A failing non-required check is recorded in the bundle but does not refute
+     * the run. The predecessor field (`fix-on-failure.ts` `steps[].required`) was
+     * declared but never read; here it is honoured.
+     */
+    required?: boolean;
+}
+export interface AcceptanceContract {
+    id?: string;
+    checks: ContractCheck[];
+    /**
+     * On red, spawn a fixer session and re-run the whole check list, up to N times.
+     * Ported from ultraapp's fix-on-failure loop. 0 disables.
+     */
+    fixOnFailureRounds?: number;
+}
+export interface CheckResult {
+    id: string;
+    type: CheckSpec['type'];
+    required: boolean;
+    passed: boolean;
+    durationMs: number;
+    /** Human-readable one-liner: the command that failed, the status we got, etc. */
+    detail: string;
+    /** Tail of captured output, byte-capped. */
+    tail?: string;
+    /** Paths (relative to the evidence dir) of files this check produced. */
+    artifacts?: string[];
+    /** Set when the check was killed by its own timeout rather than exiting. */
+    timedOut?: boolean;
+}
+export declare const DEFAULT_CHECK_TIMEOUT_MS: number;
+export declare const DEFAULT_HTTP_TIMEOUT_MS = 30000;
+export declare const DEFAULT_SCREENSHOT_TIMEOUT_MS = 60000;
+/**
+ * Parse an untrusted contract, dropping anything unrecognised. Returns undefined
+ * when nothing usable survives, so a malformed contract fails loudly at declare
+ * time rather than silently degrading to "no checks" at completion time.
+ */
+export declare function normalizeContract(raw: unknown): AcceptanceContract | undefined;
+/** True when every required check passed. Non-required failures are recorded, not fatal. */
+export declare function contractPassed(results: CheckResult[]): boolean;

package/dist/src/verify/contract.js

@@ -0,0 +1,142 @@
+/**
+ * Acceptance contracts — what the runtime itself checks before calling a run done.
+ *
+ * Every completion signal that existed before this module was the agent grading
+ * its own work: council terminated on a regex over agent prose (`consensus.ts`),
+ * autoloop's `eval_output` was whatever the Coder passed to a tool call
+ * (`autoloop/agent-tools.ts`), ultraapp's frontend gate was a sentence in a
+ * persona string (`ultraapp/council-adapter.ts`). A contract is the opposite:
+ * a caller-declared list of checks that *we* execute and whose exit codes we read.
+ *
+ * Provenance rule, and the reason `normalizeContract` exists: a contract may
+ * come from the caller or from a mode default, never from agent output. If an
+ * agent could declare its own checks we would be back to self-grading with extra
+ * steps. Nothing in the kernel reads a contract out of a node's result.
+ */
+export const DEFAULT_CHECK_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+export const DEFAULT_SCREENSHOT_TIMEOUT_MS = 60_000;
+// ─── Normalization ──────────────────────────────────────────────────────────
+function str(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+function strArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((x) => typeof x === 'string');
+    return out.length === v.length ? out : undefined;
+}
+function normalizeSpec(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    switch (r.type) {
+        case 'command': {
+            const cmd = str(r.cmd);
+            if (!cmd)
+                return undefined;
+            const args = strArray(r.args) ?? [];
+            return {
+                type: 'command',
+                cmd,
+                args,
+                cwd: str(r.cwd),
+                timeoutMs: num(r.timeoutMs),
+                expectExit: num(r.expectExit),
+            };
+        }
+        case 'http': {
+            const url = str(r.url);
+            if (!url)
+                return undefined;
+            return {
+                type: 'http',
+                url,
+                expectStatus: num(r.expectStatus),
+                timeoutMs: num(r.timeoutMs),
+                intervalMs: num(r.intervalMs),
+            };
+        }
+        case 'screenshot': {
+            const url = str(r.url);
+            if (!url || !Array.isArray(r.viewports) || r.viewports.length === 0)
+                return undefined;
+            const viewports = [];
+            for (const v of r.viewports) {
+                if (!v || typeof v !== 'object')
+                    return undefined;
+                const vv = v;
+                const width = num(vv.width);
+                const height = num(vv.height);
+                if (!width || !height)
+                    return undefined;
+                viewports.push({ width, height, label: str(vv.label) });
+            }
+            return { type: 'screenshot', url, viewports, browserBin: str(r.browserBin), timeoutMs: num(r.timeoutMs) };
+        }
+        case 'diff_policy':
+            return {
+                type: 'diff_policy',
+                maxFiles: num(r.maxFiles),
+                forbidPaths: strArray(r.forbidPaths),
+                requirePaths: strArray(r.requirePaths),
+            };
+        case 'file': {
+            const p = str(r.path);
+            if (!p)
+                return undefined;
+            return {
+                type: 'file',
+                path: p,
+                exists: typeof r.exists === 'boolean' ? r.exists : true,
+                matches: str(r.matches),
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Parse an untrusted contract, dropping anything unrecognised. Returns undefined
+ * when nothing usable survives, so a malformed contract fails loudly at declare
+ * time rather than silently degrading to "no checks" at completion time.
+ */
+export function normalizeContract(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const rawChecks = Array.isArray(r.checks) ? r.checks : undefined;
+    if (!rawChecks)
+        return undefined;
+    const checks = [];
+    for (let i = 0; i < rawChecks.length; i++) {
+        const entry = rawChecks[i];
+        if (!entry || typeof entry !== 'object')
+            continue;
+        // Accept both `{spec: {...}}` and a bare check spec, since hand-written
+        // contracts in tool calls tend to omit the wrapper.
+        const spec = normalizeSpec('spec' in entry ? entry.spec : entry);
+        if (!spec)
+            continue;
+        checks.push({
+            id: str(entry.id) ?? `${spec.type}-${i + 1}`,
+            spec,
+            required: entry.required === false ? false : true,
+        });
+    }
+    if (checks.length === 0)
+        return undefined;
+    return {
+        id: str(r.id),
+        checks,
+        fixOnFailureRounds: num(r.fixOnFailureRounds),
+    };
+}
+/** True when every required check passed. Non-required failures are recorded, not fatal. */
+export function contractPassed(results) {
+    return results.every((r) => r.passed || !r.required);
+}
+//# sourceMappingURL=contract.js.map

package/dist/src/verify/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/verify/contract.ts"],"names":[],"mappings":"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"}

package/dist/src/verify/evidence.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Evidence bundles — the machine-readable record of what was checked.
+ *
+ * A run's claim to be finished is only as good as what can be re-read after the
+ * process that made it is gone. So every verifier attempt writes a directory:
+ * the verdict and per-check results as JSON, the failure tails as plain text,
+ * whatever files the checks produced (screenshots), and the patch the run
+ * actually made, against the base commit recorded when it started.
+ */
+import type { Logger } from '../logger.js';
+import { type ChangedFile } from './baseline.js';
+import { type CheckResult } from './contract.js';
+export interface EvidenceBundle {
+    evidenceId: string;
+    runId: string;
+    /** Node that produced it, or `'run'` for a standalone `verify_run`. */
+    node: string;
+    contractId?: string;
+    createdAt: string;
+    cwd: string;
+    baseSha?: string;
+    headSha?: string;
+    passed: boolean;
+    /** Fix-on-red rounds consumed before this verdict. */
+    rounds: number;
+    results: CheckResult[];
+    changedFiles: ChangedFile[];
+    /**
+     * Digest of the working tree at the moment the checks finished. The kernel
+     * re-computes it when the run ends: if it moved, this bundle describes an
+     * earlier tree and the verdict no longer applies to what is on disk.
+     * Undefined outside a git repo, where we cannot tell.
+     */
+    treeFingerprint?: string;
+}
+export declare function evidenceRoot(runDir: string): string;
+export declare function evidenceDir(runDir: string, evidenceId: string): string;
+/** `<node>-<attempt>` — stable, sortable, and readable in a ledger row. */
+export declare function makeEvidenceId(node: string, attempt: number): string;
+export interface WriteEvidenceArgs {
+    runDir: string;
+    runId: string;
+    node: string;
+    evidenceId: string;
+    cwd: string;
+    baseSha?: string;
+    contractId?: string;
+    results: CheckResult[];
+    rounds: number;
+    logger?: Logger;
+}
+/**
+ * Write the bundle. Best-effort like the run ledger: a bundle that fails to land
+ * must not change the verdict it is describing — the verdict is already decided
+ * by `results`.
+ */
+export declare function writeEvidence(args: WriteEvidenceArgs): Promise<EvidenceBundle>;
+export declare function readEvidence(runDir: string, evidenceId: string): EvidenceBundle | undefined;
+export declare function listEvidence(runDir: string): string[];
+/** Render a bundle for the CLI. Pure — no I/O. */
+export declare function formatEvidence(bundle: EvidenceBundle): string;