Docs · PatentChecker
PatentChecker docs for evaluation, verification, and delivery risk
Use this lane for buyer evaluation, evidence verification, self-hosting, adapters, coverage scope, and the delivery-system surfaces behind vector and sequence IP review.
Patent IPDelivery riskVerificationSelf-serve
Viewing
PatentChecker testing matrix
Need another page?
Search the docs
Jump to buyers, verification, demos, self-hosting, or adapters without opening the full docs tree first.
Key sections
Mobile navigationJump to sectionOpen
Mobile navigation
Jump to section
This document defines the practical validation surface for
patentchecker.The repository has multiple kinds of checks:
- compiled JavaScript/TypeScript tests;
- source-only targeted tests;
- Python tests;
- deterministic artifact and example validation;
- CI policy and release guardrails.
The goal of this page is to make it clear which command covers which risk.
If you need one bounded runtime path before choosing a validation command, start with docs/runtime-flows.md.
60-second chooser
Use the smallest row that matches the change. Add the higher-confidence row only when the change is buyer-visible, release-visible, or crosses lane boundaries.
| Change area | Minimum local check | Higher-confidence check |
|---|---|---|
| Fresh clone, local runtime, or contributor setup | npm run contributor:smoke | npm run repo:doctor -- --json --strict-local-runtime; npm run ecosystem:doctor -- --json |
| TS/JS runtime, CLI, or shared engine behavior | npm test | affected lane recipe below; npm run sellable:v1 for buyer-visible changes |
| Demo collateral, procurement package refresh, or scenario-specific bundle families | use the matching npm run test:demo, npm run test:exposure-bundle, or npm run test:intellia-risk-bundle from the lane recipe below | npm test when shared runtime code changed; npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or the maintained workflow-family docs changed |
| MCP server tool/resource surface, manifest, or stdio startup wiring | npm run test:mcp | npm run ci:supported-surfaces-invariants when the documented MCP contract or maintained support docs changed |
| Self-serve onboarding bridge, preflight, first-run, or receipt verification | npm run test:self-serve-bridge | npm test; npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].bridge_scripts, workflow_surface.family_policies[].focused_validation_scripts, or the maintained support docs changed |
| Platform-owned self-serve packaging, billing, ops-request, evaluation, or upgrade lifecycle flows | npm run test:platform-self-serve; use npm run test:platform-self-serve:ops-request here for compatibility-wrapper changes and the same lane in ../patentchecker-platform for functional ops-request behavior; use npm run test:platform-self-serve:evaluation:delivery and npm run test:platform-self-serve:upgrade:delivery here for delegated delivery wrappers and the matching lanes in ../patentchecker-platform for functional delivery monitoring behavior; use npm run test:platform-self-serve:evaluation here for delegated evaluation delivery/follow-up wrappers plus the remaining local outcome/activation/issuance slice, and run the same lane in ../patentchecker-platform when delivery or follow-up behavior itself changed; use npm run test:platform-self-serve:upgrade here for delegated upgrade transition wrappers plus the remaining local ship/apply/return slice, and run the same lane in ../patentchecker-platform when transition behavior itself changed | npm test; npm run ci:supported-surfaces-invariants when workflow_surface.family_policies for platform:self-serve:, including focused_validation_scripts, subfamily_path_policies, or delegated-wrapper metadata, or the maintained support docs changed |
| Internal outreach, sales collateral, or prime delivery workflows | use the matching npm run test:internal-outreach, npm run test:internal-sales, or npm run test:internal-prime from the lane recipe below | npm test when shared runtime code changed; npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or the maintained boundary docs changed |
| Offline packet, buyer verification, or public release docs | npm run miec:verify; add npm run ci:public-release-surface-invariants when release docs, assets, or workflow wiring changed | npm run integrity:all -- --quiet; npm run release:mirror:smoke -- --quiet after publish |
| Watchlist, run verification, or adapter integration | npm run test:watchlist | npm run demo:watchlist; npm run verify:run -- <run_dir> after a concrete run; npm test when shared engine behavior also changed |
| Valuation source normalization, report, or signed bundle | npm run test:valuation | lane recipe below; npm run evidence-kit:check-golden when signing or canonicalization changed; npm test when shared engine behavior also changed |
| Python-backed verification or provenance helpers | npm run test:python | affected lane recipe when Python output is buyer-visible |
| Support policy, workflow family policy, or validation docs | npm run ci:supported-surfaces-invariants | npm run contributor:smoke; npm run sellable:v1 when the change alters release behavior |
| Runtime metadata, package runtime, or CI workflow security | npm run ci:runtime-metadata-invariants or npm run ci:workflow-security-invariants | npm run sellable:v1 for release-sensitive changes |
Command families
There are two command families in this repo, and they should not be treated as interchangeable.
1. Repo-health and contract checks
These confirm that contributor setup, policy wiring, release metadata, and support contracts are still aligned.
Examples:
npm run contributor:smokenpm run repo:doctor -- --json --strict-local-runtimenpm run ci:supported-surfaces-invariantsnpm run ci:public-release-surface-invariantsnpm run ci:python-surface-invariantsnpm run ci:runtime-metadata-invariantsnpm run ci:workflow-security-invariants
These checks are necessary when you change docs, policies, release wiring, or runtime metadata. They do not prove that a product lane still behaves correctly.
2. Lane behavior checks
These confirm that a concrete product or operator path still works.
Examples:
npm run demo:watchlistnpm run verify:run -- <run_dir>node dist/src/mcp/patentchecker_mcp_server.js --repo-root "$PWD" --print-manifestpatentchecker packet lint ...patentchecker value --source ...patentchecker verify <bundle_dir> ...npm testnpm run test:python
These checks are the right place to start when you changed runtime behavior, verification behavior, or user-visible artifacts.
Use both families when a change crosses product behavior and policy or release boundaries.
Primary commands
| Command | Scope | Includes | Does not include | When to use |
|---|---|---|---|---|
npm test | Main JS/TS regression suite | npm run build plus all compiled *.test.js files under dist/, discovered by scripts/run_all_tests.mjs | Source-only JS tests outside dist; Python tests | Default repo regression check before and after code changes |
npm run test:mcp | Focused MCP lane regression | npm run build, MCP manifest print via node dist/src/mcp/patentchecker_mcp_server.js --repo-root "$PWD" --print-manifest, plus the mcp group in scripts/run_all_tests.mjs | Unrelated JS suites; Python tests; support-policy checks | MCP server startup, manifest, tool wiring, or repo-root resolution changes |
npm run test:self-serve-bridge | Focused repo-owned self-serve bridge regression | npm run build plus the self-serve-bridge group in scripts/run_all_tests.mjs: doctor, first-run, license-status, provision, and receipt verification coverage | Platform-owned issuance and lifecycle flows; unrelated JS suites; Python tests | Self-serve onboarding bridge, preflight, first-run, or receipt verification changes |
npm run test:platform-self-serve | Focused platform self-serve wrapper regression | npm run build plus the platform-self-serve group in scripts/run_all_tests.mjs: readiness-bundle, starter-package, receipt-package, rotation, invoice, and billing-queue coverage | ops-request, evaluation, and upgrade lifecycle clusters; unrelated JS suites; Python tests | Platform-owned wrapper, packaging, rotation, billing, or queueing changes before widening to a lifecycle cluster |
npm run test:platform-self-serve:ops-request | Focused platform self-serve ops-request wrapper regression in this repo | npm run build plus the platform-self-serve:ops-request group in scripts/run_all_tests.mjs, which now validates compatibility delegation into patentchecker-platform | Functional queue behavior, other lifecycle clusters, unrelated JS suites, Python tests | Wrapper or handoff changes under platform:self-serve:ops-request:*; run the same lane in ../patentchecker-platform when queue behavior itself changed |
npm run test:platform-self-serve:evaluation:delivery | Focused delegated evaluation delivery wrapper regression in this repo | npm run build plus the platform-self-serve:evaluation:delivery group in scripts/run_all_tests.mjs, which validates compatibility delegation for platform:self-serve:evaluation:{report,alert,scheduler} | Functional delivery monitoring behavior, remaining evaluation implementation, other lifecycle clusters, unrelated JS suites, Python tests | Wrapper or handoff changes under platform:self-serve:evaluation:{report,alert,scheduler}; run the same lane in ../patentchecker-platform when delivery monitoring behavior itself changed |
npm run test:platform-self-serve:upgrade:delivery | Focused delegated upgrade delivery wrapper regression in this repo | npm run build plus the platform-self-serve:upgrade:delivery group in scripts/run_all_tests.mjs, which validates compatibility delegation for platform:self-serve:upgrade:{report,alert,scheduler} | Functional delivery monitoring behavior, remaining upgrade implementation, other lifecycle clusters, unrelated JS suites, Python tests | Wrapper or handoff changes under platform:self-serve:upgrade:{report,alert,scheduler}; run the same lane in ../patentchecker-platform when delivery monitoring behavior itself changed |
npm run test:platform-self-serve:evaluation | Focused platform self-serve evaluation regression | npm run build plus the platform-self-serve:evaluation group in scripts/run_all_tests.mjs, including the delegated delivery wrapper lane, the delegated delivery/follow-up wrapper lane, and the remaining local evaluation outcome/activation/issuance tests | Upgrade lifecycle, unrelated JS suites, Python tests | Broader platform:self-serve:evaluation:* changes that touch delegated delivery or follow-up wrappers, local outcome handling, local activation handling, or local issuance/packaging behavior |
npm run test:platform-self-serve:upgrade | Focused platform self-serve upgrade regression | npm run build plus the platform-self-serve:upgrade group in scripts/run_all_tests.mjs, including the delegated upgrade delivery wrapper lane, the delegated upgrade transition wrapper lane, and the remaining local ship/apply/return tests | Evaluation lifecycle, unrelated JS suites, Python tests | Broader platform:self-serve:upgrade:* changes that touch delegated transition wrappers, local shipping, local application, or return packaging behavior |
npm run test:internal-outreach | Focused internal outreach regression | npm run build plus the internal-outreach group in scripts/run_all_tests.mjs: contact-research queue, patch/finalize, drafts, send-ready, dashboard, ops-cycle, snapshot, momentum, and close-loop coverage | Sales or prime workflows; unrelated JS suites; Python tests | outreach:* changes under scripts/internal/outreach/ |
npm run test:internal-sales | Focused internal sales collateral regression | npm run build plus the internal-sales group in scripts/run_all_tests.mjs: court-ready offer and court-ready sales-kit coverage | Outreach or prime workflows; unrelated JS suites; Python tests | sales:* changes under scripts/internal/sales/ |
npm run test:internal-prime | Focused internal prime-delivery regression | npm run build plus the internal-prime group in scripts/run_all_tests.mjs: signed-receipt preparation/validation, packet-c closure, evidence bundle, metadata validation, finalize, and ops SLO coverage | Outreach or sales workflows; unrelated JS suites; Python tests | prime:* changes under scripts/internal/prime/ |
npm run test:watchlist | Focused watchlist regression | npm run build plus the watchlist group in scripts/run_all_tests.mjs: watchlist compile/runner coverage, run verification, alerts summary views, and adapter/scope boundary tests | End-to-end demo:watchlist; unrelated JS suites; Python tests | Watchlist authoring, runner, adapter contract, or run-verification changes that do not need the full repo suite yet |
npm run test:valuation | Focused valuation regression | npm run build plus the valuation group in scripts/run_all_tests.mjs: valuation runtime and CLI coverage | Evidence-kit golden checks, full JS suite, Python tests | Valuation normalization, scoring, report, or CLI changes before widening to bundle-specific checks |
npm run test:gov-proof | Targeted source JS test | tests/gov_proof_bundle.test.js | The broader JS suite; Python tests | Fast verification when touching the gov proof bundle path |
npm run test:python | Python regression gate | scripts/ci/pytest_gate.sh, pinned Python from .python-version, temporary virtualenv, locked dependencies from tests/requirements-ci.txt, pytest -q, fail-closed on interpreter drift and skipped/deselected/xfail | JS/TS tests | Any change that touches Python code under src/patentchecker/, patentchecker/, verify/, or Python-backed workflows |
npm run contributor:smoke | Maintained first-pass contributor preflight | npm run repo:doctor -- --json --strict-local-runtime plus npm run validate:examples via scripts/contributor_smoke.js | Full JS regression suite; Python tests; higher-order release gates | Fresh clones, contributor-machine sanity checks, or the first repo-owned command to run before choosing a wider validation path |
npm run test:demo | Focused demo/collateral regression | npm run build plus the demo group in scripts/run_all_tests.mjs: CRISPR demo, demo offline packet, gov proof, NASA horizon package, NAVSEA proof bundle, and NAVSEA outreach package coverage | Exposure or Intellia scenario bundles; unrelated JS suites; Python tests | demo:* changes that refresh collateral, public demo packets, or procurement-ready packages |
npm run test:exposure-bundle | Focused exposure-bundle regression | npm run build plus the exposure-bundle group in scripts/run_all_tests.mjs: builder, tools, and pipeline coverage for exposure-bundle:v1:* | Demo or Intellia bundle families; unrelated JS suites; Python tests | exposure-bundle:* changes |
npm run test:intellia-risk-bundle | Focused Intellia risk bundle regression | npm run build plus the intellia-risk-bundle group in scripts/run_all_tests.mjs: seed/build/pipeline coverage for intellia-risk-bundle:v1:* | Demo or exposure-bundle families; unrelated JS suites; Python tests | intellia-risk-bundle:* changes |
npm run validate:examples | Example/build validation | Build plus example/schema validation via scripts/validate_examples.js | Full JS regression suite; Python tests | When touching schemas, examples, fixtures, or generated example outputs |
npm run miec:verify | MIEC evidence path | validate:examples plus scripts/miec_verify.js | General repo regression surface | When touching MIEC or offline packet verification paths |
npm run evidence-kit:check-golden | Deterministic evidence-kit fixture | Golden fixture regeneration/check via scripts/generate_evidence_kit_golden_fixture.mjs | General app behavior | When touching evidence-kit canonicalization, packaging, signing, or deterministic output rules |
npm run ci:runtime-metadata-invariants | Runtime metadata policy | Node version alignment across package metadata, CI, and runtime descriptors | Functional behavior | When touching package.json, CI runtime setup, Docker runtime, or release metadata |
npm run ci:python-surface-invariants | Python workflow contract policy | Supported repo-run Python entrypoints, pinned Python 3.12 baseline, pytest gate, hashed requirements, workflow docs, and no-package-install stance via scripts/ci/check_python_surface_invariants.js | Runtime behavior of Python code itself | When touching Python entrypoints, Python workflow docs, pytest gate, or packaging boundaries |
npm run ci:supported-surfaces-invariants | Support-tier policy | Machine-readable support-tier policy, contributor entry map, canonical npm workflow inventory under workflow_surface.primary_npm_entrypoints, exclusion of workflow_surface.non_default_prefixes from that primary inventory, non-default family policy under workflow_surface.family_policies, controlled target_home and transition_phase migration values and support-level combinations, grouped-family script_path_prefix guards, nested-cluster subfamily_path_policies, repo-owned bridge_scripts allowlists, family-level focused_validation_scripts, non-default family max_script_count caps, support-contract docs, workflow enforcement, and sellable gate alignment via scripts/ci/check_supported_surfaces_invariants.js | Functional behavior of the product itself | When touching README.md, docs/mcp-server.md, docs/core-surfaces.md, docs/workflow-family-policy.md, SUPPORTED_SURFACES.md, CI enforcement wiring, or the support policy JSON |
npm run ci:public-release-surface-invariants | Public release contract policy | Machine-readable public release asset policy, release workflow asset wiring, mirror allowlist, buyer/release docs, and release-gate filter alignment via scripts/ci/check_public_release_surface_invariants.js | Runtime behavior of the product itself | When touching public release assets, release docs, mirror automation, or release workflow asset wiring |
npm run ci:workflow-security-invariants | CI/workflow policy | Workflow permission and action pinning rules described in docs/ci-invariants.md | Product behavior | When touching .github/workflows/ or release automation |
npm run ci:packetify-repro | Cross-environment determinism | Host vs container packetify reproducibility via scripts/ci/packetify_reproducibility.sh | General business logic | When touching packetify, archive determinism, or bundle serialization |
npm run sellable:v1 | Composite product gate | validate:examples, npm test, contract descriptor check, workflow security invariants, runtime metadata invariants, Python surface invariants, buyer-surface checks, notices/compliance checks via scripts/sellable_v1_gate.js | Python tests | Pre-merge or pre-release confidence check for user-visible and buyer-visible changes |
npm run integrity:all -- --quiet | Buyer-path integrity ceremony | validate:examples, npm test, MIEC verification, demo offline packet build, zip safety, native verify, optional mirror verification via scripts/integrity_all.js | Python tests unless run separately | Release and public-artifact confidence checks |
npm run release:mirror:smoke -- --quiet | Public mirror smoke | Download current-tag public mirror bytes, validate release_assets.sha256, run ZIP safety, extract demo_offline_packet.zip, run packet-native verification, and emit artifacts/ops_proof.json via scripts/integrity_all.js --mirror-only | Local build/test validation and Python tests | After publishing a tag, or when validating the public mirror path in release-gate |
npm run validate:shadow | Shadow-root validation | validate:examples in a temporary shadow repo | Full sellable gate; Python tests | When local dist/ writes or working tree I/O make in-place validation unreliable |
npm run sellable:v1:shadow | Shadow-root composite gate | sellable:v1 in a temporary shadow repo | Python tests | Same use case as above, but for the higher-order sellable gate |
Lane-based validation recipes
Use these recipes when the lane is clear but the exact command set is not.
Each lane is split into a minimum check set and a higher-confidence set so ordinary changes do not default to the broadest gate.
Buyer and offline verification surface
Use this recipe when changing released packets, buyer verification docs, packet validation logic, or public release contract wiring.
Fastest repo-local smoke:
npm run miec:verifynpm run ci:public-release-surface-invariantswhen touching public release docs, release assets, or release workflow wiringnpm run validate:exampleswhen packet inputs, examples, or normative docs changed
Artifact-side confirmation when you already have a packet:
patentchecker packet lint --packet-dir <PACKET_DIR> --validate-modules --validate-views --validate-zip
Policy and release-contract checks:
npm run ci:public-release-surface-invariants
Higher-confidence:
npm run integrity:all -- --quietnpm run release:mirror:smoke -- --quietafter publish or when validating the public mirror path
Watchlist and monitoring surface
Use this recipe when changing watchlist authoring, runner behavior, adapters, packet views, or run verification.
Fastest targeted regression:
npm run test:watchlist
Focused behavior confirmation:
npm run demo:watchlistnpm run watchlist:run -- --watchlist <watchlist.v0.1.json> --out-dir <DIR> --run-at <ISO-8601Z>npm run verify:run -- <run_dir>
Regression floor:
npm run test:watchlist
Higher-confidence:
patentchecker packet lint --run-dir <RUN_DIR> --packet-dir <PACKET_DIR> --validate-viewswhen packet/view logic changednpm run validate:exampleswhen schemas, examples, or shipped fixtures changednpm testwhen the same change also touched shared engine behavior outside the watchlist lane
Demo and scenario-specific bundle families
Use this recipe when changing demo collateral refresh paths under
demo:* or scenario-specific bundle pipelines under exposure-bundle:* and intellia-risk-bundle:*. These families remain explicitly secondary, but the policy now records lane-specific maintainer entrypoints under workflow_surface.family_policies[].focused_validation_scripts and groups their entrypoint scripts under scripts/demo/, scripts/exposure_bundle/, and scripts/intellia_risk_bundle/.Fastest targeted regression:
npm run test:demofordemo:*npm run test:exposure-bundleforexposure-bundle:*npm run test:intellia-risk-bundleforintellia-risk-bundle:*
Higher-confidence:
npm testwhen shared runtime code or common helper behavior also changednpm run ci:supported-surfaces-invariantswhenworkflow_surface.family_policies[].focused_validation_scripts,script_path_prefix, or the maintained workflow-family docs changed
Self-serve onboarding and receipt-verification bridge
Use this recipe when changing the repo-owned self-serve bridge: workspace provisioning, preflight checks, first-run orchestration, license status, or offline receipt verification. The bridge allowlist is tracked under
workflow_surface.family_policies[].bridge_scripts, and its named maintainer entrypoint is tracked under workflow_surface.family_policies[].focused_validation_scripts; broader lifecycle flows now sit under platform:self-serve:*.Fastest targeted regression:
npm run test:self-serve-bridge
Higher-confidence:
npm testnpm run ci:supported-surfaces-invariantswhenworkflow_surface.family_policies[].bridge_scripts,workflow_surface.family_policies[].focused_validation_scripts, or the maintained support docs changed
Platform-owned self-serve issuance and lifecycle ops
Use this recipe when changing readiness bundles, starter packaging, receipt-packaging helpers, token or license rotation, invoice export or delivery, billing queues, ops-request processing, evaluation issuance, or upgrade lifecycle flows under
platform:self-serve:*. The supported named entrypoints for these clusters are tracked under workflow_surface.family_policies[].focused_validation_scripts, and the grouped lifecycle directories are pinned under workflow_surface.family_policies[].subfamily_path_policies. The delegated ops-request slice records wrapper_only, delegated_to_repo, delegate_helper_path, and delegated_script_path_prefix, while the partially delegated evaluation and upgrade slices record delegated_scripts with the same repo/helper/path metadata, so the policy can distinguish checked-in compatibility wrappers from in-repo functional implementations. The ops-request cluster, the evaluation delivery-monitoring trio, the evaluation delivery/follow-up trio, and the delegated upgrade delivery and transition wrappers are now functionally owned by patentchecker-platform, so this repo only validates the compatibility wrappers for those slices.Fastest wrapper-focused regression:
npm run test:platform-self-serve
Add the affected lifecycle cluster:
npm run test:platform-self-serve:ops-requestwhen touchingplatform:self-serve:ops-request:*wrappers in this repocd ../patentchecker-platform && npm run test:platform-self-serve:ops-requestwhen the queue behavior itself changednpm run test:platform-self-serve:evaluation:deliverywhen touchingplatform:self-serve:evaluation:{report,alert,scheduler}wrappers in this repocd ../patentchecker-platform && npm run test:platform-self-serve:evaluation:deliverywhen evaluation delivery monitoring behavior itself changednpm run test:platform-self-serve:evaluationwhen touching delegatedplatform:self-serve:evaluation:{mark-delivery,set-follow-up,mark-follow-up}wrappers or the remaining localplatform:self-serve:evaluation:outcome/activation/issuance slicecd ../patentchecker-platform && npm run test:platform-self-serve:evaluationwhen evaluation delivery or follow-up behavior itself changednpm run test:platform-self-serve:upgrade:deliverywhen touchingplatform:self-serve:upgrade:{report,alert,scheduler}wrappers in this repocd ../patentchecker-platform && npm run test:platform-self-serve:upgrade:deliverywhen upgrade delivery monitoring behavior itself changednpm run test:platform-self-serve:upgradewhen touching delegated upgrade transition wrappers or the remaining localplatform:self-serve:upgrade:{ship,mark-applied,return}slicecd ../patentchecker-platform && npm run test:platform-self-serve:upgradewhen upgrade transition behavior itself changed
Higher-confidence:
npm testnpm run ci:supported-surfaces-invariantswhenworkflow_surface.family_policiesforplatform:self-serve:, includingfocused_validation_scripts,subfamily_path_policies,wrapper_only,delegated_scripts,delegated_to_repo,delegate_helper_path, ordelegated_script_path_prefix, or the maintained support docs changed
Internal outreach, sales, and prime operating families
Use this recipe when changing script-backed internal operating workflows under
outreach:*, sales:*, or prime:*. These families stay out of the default product surface, but their focused maintainer entrypoints are still recorded under workflow_surface.family_policies[].focused_validation_scripts so maintainers do not need raw file lists.Fastest targeted regression:
npm run test:internal-outreachforoutreach:*npm run test:internal-salesforsales:*npm run test:internal-primeforprime:*
Higher-confidence:
npm testwhen shared runtime code or common helper behavior also changednpm run ci:supported-surfaces-invariantswhenworkflow_surface.family_policies[].focused_validation_scripts,script_path_prefix, or the maintained boundary docs changed
MCP automation surface
Use this recipe when changing the stdio server startup path, tool wiring, resource manifests, repo-root resolution, or the documented MCP contract in docs/mcp-server.md.
Fastest focused regression:
npm run test:mcp
Higher-confidence:
npm run ci:supported-surfaces-invariantswhen changingpackage.json, docs/mcp-server.md, or the maintained support-tier docs
Patent valuation and evidence bundle surface
Use this recipe when changing valuation normalization, scoring, bundle generation, or offline bundle verification.
Fastest targeted regression:
npm run test:valuation
Concrete behavior confirmation:
npm run buildnode dist/src/cli/patentchecker.js value --source examples/patent_valuation/epo_lnp_source.v0.1.json --cache-dir ./out/valuation-cache --signing-key tests/fixtures/evidence_kit/keys/ed25519_privkey.pem --out-dir ./out/epo_lnp.run --emit-markdown --zip --overwritenode dist/src/cli/patentchecker.js verify ./out/epo_lnp.run/bundle --expected-fingerprint <ed25519:...>
Focused normalization check:
node dist/src/cli/patentchecker.js patent-valuation ingest --source examples/patent_valuation/epo_lnp_source.v0.1.json --out ./out/epo_lnp.inputs.json --cache-dir ./out/valuation-cache
Regression floor:
npm run test:valuationnpm run validate:examples
Higher-confidence:
npm run evidence-kit:check-goldenwhen touching canonicalization, signing, or bundle serializationnpm testwhen the same change also touched shared engine behavior outside the valuation lane
Python-backed verification and provenance helpers
Use this recipe when changing Python-backed verification, evidence retrieval, provenance helpers, or documented repo-run Python entrypoints.
Use docs/node-python-boundary.md when you need to decide whether the change is in a Python-owned workflow or only consumes Python-emitted artifacts from a Node-first lane.
Fastest regression check:
npm run test:python
Contract check:
npm run ci:python-surface-invariants
Higher-confidence:
- pair the Python checks above with the higher-confidence gate from the affected product lane when Python changes alter buyer-visible or release-visible behavior
Support policy and release guardrails
Use this recipe when changing contributor policy, support tiers, release metadata, or workflow security rules.
Fastest repo-health check:
npm run contributor:smoke
Policy checks:
npm run ci:supported-surfaces-invariantsnpm run ci:runtime-metadata-invariantsnpm run ci:workflow-security-invariantswhen.github/workflows/**changed
Higher-confidence:
npm run sellable:v1npm run integrity:all -- --quietwhen the same change also affects buyer-visible release behavior
What npm test actually means
npm test is the default JavaScript/TypeScript regression command. It does two things:- Builds the repository with
npm run build. - Recursively discovers every compiled
*.test.jsfile underdist/and runs them withnode --test.
That makes it the correct default for most TS/JS changes, but it is not the entire repo validation surface.
When the lane is clear,
npm run test:watchlist, npm run test:valuation, npm run test:mcp, npm run test:self-serve-bridge, npm run test:demo, npm run test:exposure-bundle, npm run test:intellia-risk-bundle, the npm run test:platform-self-serve* family, and the npm run test:internal-* family keep maintainers on focused entrypoints instead of forcing raw node --test file lists or the full suite.Notably,
npm test does not cover:- tests/gov_proof_bundle.test.js, which is source-only and has its own command;
- the Python suite executed by
npm run test:python; - release/invariant checks such as runtime metadata, workflow security, packetify reproducibility, or integrity ceremony checks.
CI workflow mapping
The main workflow files map to the validation surface as follows.
| Workflow | Purpose | Main checks |
|---|---|---|
| .github/workflows/validate.yml | Default PR/push sellable gate | runtime metadata invariants, Python surface invariants, supported surfaces invariants, public release surface invariants, workflow security invariants, npm audit, npm run sellable:v1, Python gate |
| .github/workflows/tripwire.yml | Main-branch policy enforcement | public audit, gitleaks, runtime/workflow invariants, Python surface invariants, supported surfaces invariants, public release surface invariants, validate:examples, npm test, evidence-kit golden, Python gate |
| .github/workflows/release-gate.yml | Release-surface gate | public release surface invariants, evidence-kit golden, npm run integrity:all, npm run release:mirror:smoke |
| .github/workflows/release.yml | Release build/publish path | runtime metadata invariants, Python surface invariants, supported surfaces invariants, public release surface invariants, workflow security invariants, npm run sellable:v1, packaging/publication, npm run release:mirror:smoke after public mirror publish |
| .github/workflows/packetify-repro.yml | Deterministic packetify cross-check | npm run ci:packetify-repro |
| .github/workflows/miec.yml | MIEC path verification | npm run validate:examples plus MIEC-specific checks |
Change-based guidance
Use this as the minimum bar by change type.
| Change type | Minimum local validation |
|---|---|
TS/JS business logic under src/ | npm test |
demo:* collateral, proof-bundle, or procurement-package behavior | npm run test:demo; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained workflow-family docs changed |
| Buyer verification docs, packet validation logic, or offline packet contract changes | npm run miec:verify; add npm run ci:public-release-surface-invariants when release docs, assets, or workflow wiring changed |
exposure-bundle:* scenario-bundle behavior | npm run test:exposure-bundle; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained workflow-family docs changed |
intellia-risk-bundle:* scenario-bundle behavior | npm run test:intellia-risk-bundle; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained workflow-family docs changed |
| MCP server tool, resource, manifest, or stdio startup behavior | npm run test:mcp; add npm run ci:supported-surfaces-invariants when the documented contract changed |
| Repo-owned self-serve bridge behavior | npm run test:self-serve-bridge; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].bridge_scripts or workflow_surface.family_policies[].focused_validation_scripts changed |
| Platform-owned self-serve wrapper, packaging, billing, or queueing behavior | npm run test:platform-self-serve; add the affected lifecycle cluster command when the change also touches ops-request, evaluation, or upgrade |
platform:self-serve:ops-request:* wrapper behavior in this repo | npm run test:platform-self-serve:ops-request; add cd ../patentchecker-platform && npm run test:platform-self-serve:ops-request when queue behavior changed |
platform:self-serve:evaluation:{report,alert,scheduler} wrapper behavior in this repo | npm run test:platform-self-serve:evaluation:delivery; add cd ../patentchecker-platform && npm run test:platform-self-serve:evaluation:delivery when delivery monitoring behavior changed |
Delegated platform:self-serve:evaluation:{mark-delivery,set-follow-up,mark-follow-up} wrapper behavior in this repo | npm run test:platform-self-serve:evaluation; add cd ../patentchecker-platform && npm run test:platform-self-serve:evaluation when delivery or follow-up behavior changed |
platform:self-serve:upgrade:{report,alert,scheduler} wrapper behavior in this repo | npm run test:platform-self-serve:upgrade:delivery; add cd ../patentchecker-platform && npm run test:platform-self-serve:upgrade:delivery when delivery monitoring behavior changed |
Delegated platform:self-serve:upgrade:{mark-delivery,set-follow-up,mark-follow-up,mark-outcome} wrapper behavior in this repo | npm run test:platform-self-serve:upgrade; add cd ../patentchecker-platform && npm run test:platform-self-serve:upgrade when upgrade transition behavior changed |
Remaining local platform:self-serve:evaluation: outcome, activation, issuance, and packaging behavior | npm run test:platform-self-serve:evaluation |
Remaining local platform:self-serve:upgrade:{ship,mark-applied,return} lifecycle behavior | npm run test:platform-self-serve:upgrade |
outreach:* operating workflow behavior | npm run test:internal-outreach; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained boundary docs changed |
sales:* collateral workflow behavior | npm run test:internal-sales; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained boundary docs changed |
prime:* delivery workflow behavior | npm run test:internal-prime; add npm run ci:supported-surfaces-invariants when workflow_surface.family_policies[].focused_validation_scripts, script_path_prefix, or maintained boundary docs changed |
| Watchlist authoring, runner behavior, adapter integration, or run verification | npm run test:watchlist |
| Valuation normalization, scoring, report, or CLI behavior | npm run test:valuation; add npm run validate:examples when examples or shipped outputs changed |
| Source-only gov proof bundle path | npm run test:gov-proof |
Python code under src/patentchecker/, patentchecker/, or verify/ | npm run test:python |
| Python workflow contract, pytest gate, or packaging boundary | npm run ci:python-surface-invariants and npm run test:python |
| Support policy, contributor entry map, MCP support contract, or support-tier enforcement wiring | npm run ci:supported-surfaces-invariants |
| Fresh clone or contributor-machine sanity check | npm run contributor:smoke |
| Public release asset contract, mirror allowlist, or release workflow asset wiring | npm run ci:public-release-surface-invariants |
| Public mirror bytes after publish | npm run release:mirror:smoke -- --quiet |
| Schemas, examples, fixtures, normative docs | npm run validate:examples |
| Evidence-kit signing/canonicalization/bundle serialization | npm test and npm run evidence-kit:check-golden |
| Packetify/archive determinism | npm test and npm run ci:packetify-repro |
| CI/workflow metadata or runtime setup | npm run ci:workflow-security-invariants and npm run ci:runtime-metadata-invariants |
| Buyer-facing, release-facing, or packaging surface | npm run sellable:v1 |
| Public release or offline verification path | npm run integrity:all -- --quiet |
RepoIntel and Generated Wiki Note
The generated testing page under docs/wiki/testing.md is useful for orientation, but it is an inferred summary and may under-report the live repo surface.
In particular:
- not every supported validation command is named
test:*; - some high-signal validation commands live under
validate:*,evidence-kit:*,ci:*,sellable:*, andintegrity:*; - the generated wiki may sample only a subset of test files even when the repository contains a much larger test inventory under
tests/,verify/, andsrc/**/*.test.*.
Treat the following as the source of truth, in this order:
- this page for the practical validation contract;
config/supported_surfaces.policy.v0.1.jsonfor the machine-readable support-tier map, canonical npm workflow inventory, non-default prefix exclusions, non-default family policy, controlledtarget_homeandtransition_phasevalues, support-level combinations, grouped-familyscript_path_prefixguards, nested lifecyclesubfamily_path_policies, repo-ownedbridge_scriptsallowlists, family-levelfocused_validation_scripts, andmax_script_countcaps;config/public_release_surface.policy.v0.1.jsonfor the machine-readable public release asset map;- SUPPORTED_SURFACES.md for support-level policy;
- package.json for the current command surface;
- the actual paths under
tests/,verify/, andsrc/**/*.test.*for the live file inventory.
If you need a quick local inventory instead of an inferred wiki view, use:
BashRunnable example
rg --files tests src verify | rg '(^tests/|\\.test\\.(ts|js|py)$|/test_[^/]+\\.py$)'Support stance
The commands in this file are the supported validation entrypoints for repository work.
By contrast:
- ad hoc direct invocation of internal helper scripts under
scripts/lib/**is not a supported validation contract; - generated wiki pages under
docs/wiki/are reference material, not the source of truth for test policy; npm run test:pythonis the supported contributor-facing entrypoint for the Python gate, even though it is implemented by scripts/ci/pytest_gate.sh;- a passing
npm testresult should not be interpreted as a full release gate unless the relevant higher-order checks also passed.