feat(sdk): add finding validation

[ianw-oai]

Summary

The SDK can scan repositories, but it has no method to validate one existing finding. Applications that import findings must use the CLI or start a repository scan. This change adds security.validate({ repositoryPath, finding }) for that use case.

Changes

The new method accepts finding text or a JSON object. It uses the existing validation skill, SDK runtime, authentication, and event reader. It returns a disposition, a Markdown report, the thread ID, and the evidence directory. It does not start a repository scan or change source files.

Validation keeps evidence outside the repository, supports cancellation, and rejects incomplete or invalid results. The change also adds SDK documentation, focused tests, and an installed-package type check.

Testing

• Full suite with seed 12345: 1,560 passed, 30 skipped, 0 failed.
• Full suite with seed 4162224813: 1,560 passed, 30 skipped, 0 failed.
• Focused validation tests: 10 passed. Shared event-reader tests: 36 passed.
• pnpm run types, pnpm run format, and git diff --check: passed.
• Package build and installed-package checks: passed, including public imports, NodeNext types, CLI entry points, bundled plugin files, and the bundled runtime.
• The built SDK completed a request through the real Codex executable to a local synthetic endpoint. It returned the expected structured result, exposed no scan tools, and left the synthetic repository unchanged. This checks process and result handling, not finding quality.

Risk and rollout

This adds an SDK method. CLI commands, flags, defaults, and plugin files do not change. Finding strings are literal text, not paths to read. A reportable result can rely on static analysis; callers must read the report for evidence and proof gaps.

The API requires a package release. This PR does not change the package version.

Public disclosure review

• No customer, partner, prospect, or user identities, data, or identifying details are included.
• No credentials, personal data, private source, scan findings, or nonpublic links or tickets are included.
• I reviewed the branch name, title, description, commits, changes, comments, logs, screenshots, attachments, and links for public disclosure.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-08-22T00:15:46.848049Z	86ed51d	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[mldangelo-oai]

Reviewed commit 86ed51df6bb5cda81d98058ac70d4691cb91c820 and found no blocking issues.

Verified 187 passing tests across the API, event-reader, and configuration suites. Type checking and git diff --check passed, and the filesystem-sandbox test passed separately.

Nonblocking release follow-up: run a real-model smoke test against known-positive, known-negative, and insufficient-evidence fixtures. The synthetic endpoint check establishes process integration, not validation quality.