Repository navigation
Phase 1 evidence loop: SEC facts, evidence drafts, verification and review gate - #5
Merged
Merged
Conversation
The runner fetched SEC XBRL companyfacts and discarded it. It now normalizes revenue, net income, diluted EPS, operating cash flow and shares outstanding into facts that cite the accession, form, filing date, concept, unit and period, excludes values filed on or after the as_of date, and stores each fact as versioned FACT evidence. The snapshot gains `secFacts` (facts + issues) without the raw payload. Co-Authored-By: Claude Opus 5.5 <[email protected]>
POST /api/v1/research/:jobId/draft turns a succeeded job's snapshot into version 1 of a research artifact draft without any model call. Every SEC fact links to its evidence row and citation; market data and expectations stay in separate sections; gaps are listed as unknowns; thesis, scenarios and falsifiers are left for a person to author. Creation is idempotent, audited once, and refused when cited evidence is outside the job's workspace and security. Snapshots now record the evidence rows each job wrote. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Every new draft is checked in the same batch that creates it. Blocking checks cover missing, foreign or wrong-kind evidence, number/unit/ period/citation tie-out against the stored evidence row, units per metric, incomplete citations, and filings or periods at or past the as_of cutoff. Warnings cover cross-source EPS divergence and every draft unknown. Issues are stored in the new verification_issues table (migration 0008, tenant-guarded) with stable fingerprints, so re-checks reopen, keep or resolve them idempotently. Blocking issues close only on a passing re-check; editors may acknowledge warnings with a note. Draft artifacts now link to their research job. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The research result view gains an evidence draft panel: create the draft, see the blocking/warning gate, acknowledge warnings with a note, re-run checks, read each SEC fact with its filing link, accession and evidence id, and submit, approve, request changes, reject or publish. POST /api/v1/research/:jobId/draft/review delegates to the platform approval and publish actions, which now refuse approval or publication while a version has an open blocking issue, and refuse a research draft that was never verified. Approval requests only move draft versions into review, and generic artifact saves can no longer write to or forge research drafts. Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/phase1-gate.test.ts drives only HTTP route handlers from a fixture research job to a verified, fully cited draft, through human approval to publication, and shows that a draft whose as_of predates every filing, or whose evidence stops tying out, cannot be approved. `pnpm local:verify:e2e` (run in CI) now performs the same review loop against the real Worker and local D1, including refusing to publish before approval, and the D1 integrity script checks the new draft-job and verification-issue tenant guards. Co-Authored-By: Claude Opus 5.5 <[email protected]>
README (English and Chinese), roadmap, architecture plan, architecture map, development, operations and local fixture guides now describe SEC normalization, deterministic evidence drafts, verification issues and the owner-approved publish gate, what they do and do not prove, and what comes next. The changelog records steps 3 to 5. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The integrity-check descriptions in both READMEs, the development guide and the local fixture guide now include the draft-job and verification-issue tenant guards, list the Phase 1 test files, and state that the fixture run proves the draft review loop but not normalization of real SEC data. Co-Authored-By: Claude Opus 5.5 <[email protected]>
axlezhao
added a commit
that referenced
this pull request
Sep 28, 2026
Phase 1 evidence loop: SEC facts, evidence drafts, verification and review gate
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Completes the Phase 1 gate in
docs/PRODUCT_ARCHITECTURE_PLAN.md§14: a user can go from a research job to a reviewable, cited draft without any model, and nothing with an open blocking issue can be approved or published.lib/research/normalize.ts): the runner used to fetch SEC XBRLcompanyfactsand discard it. It now keeps revenue, net income, diluted EPS, operating cash flow and shares outstanding as versionedFACTevidence, each cited to accession, form, filing date, concept, unit and period. Values filed on or afteras_ofare excluded; restatements, year-to-date durations and multi-class ambiguities are handled explicitly.lib/research/draft.ts,POST/GET /api/v1/research/:jobId/draft): one draft per job, every number linked to anevidence_id, gaps listed as unknowns, and thesis, scenarios and falsifiers left empty for a person. Idempotent under concurrent requests.lib/research/verify.ts, migration0008): blocking checks cover evidence existence, ownership and kind; number/unit/period/citation tie-out; per-metric units; citation completeness; and theas_ofcutoff. Warnings cover EPS cross-check divergence and every draft unknown. Blocking issues close only on a passing re-check; editors acknowledge warnings with a note.app/research-draft.tsx,/draft/review): a draft panel in the result view. Platform approval and publish refuse any version with an open blocking issue and any research draft that was never verified; only owners approve. Approval requests only movedraftversions into review, and genericartifact.savecan no longer overwrite or forge research drafts.tests/phase1-gate.test.tsruns the full loop through HTTP routes.pnpm local:verify:e2e(already in CI) now builds, verifies, reviews and publishes a draft on the real Worker and local D1.No LLM is called anywhere.
Verification
pnpm run lintpnpm run typecheckpnpm test: 177 unit tests (130 before) plus build and SSR checksec-normalize,research-draft,research-verify,research-review,phase1-gate. Key guards were checked by deliberately breaking them and confirming the tests fail.pnpm db:local:migrate,pnpm db:local:verify-integrity(now including the two new tenant guards) andpnpm local:verify:e2epass locallyData and security impact
0008_verification_issues.sql: adds theverification_issuestable,research_artifact_versions.verified_at/verifier_version, andresearch_artifacts.research_job_idwith a partial unique index. It only adds columns and tables, and it includes tenant-guard triggers for issues and draft-to-job links.approval.requestnow requires adraftversion,approval.decide(approve) andartifact.publishgo through the verification gate, andartifact.saverejects research-draft targets andevidence_draftcontent.as_of..invalidURLs.Documentation and limitations
Rollout: apply migration
0008before deploying. Snapshots from before this change cannot become drafts (409); re-run the job.