Docs · OGN platform

GPU-native genomics operating system

From raw reads to GIAB-validated variant calls in a continuous GPU pipeline. This is the control surface for the engine: CLI, pipelines, benchmarks, and deployment runbooks.

CUDA 12+Hopper · AmpereGIAB-validated flowsSchemas stable

Viewing

PatentChecker self-serve starter

BioCost quickstart Docs overview Benchmark pack Example pipelines GitHub

Self-Serve Client Starter (one-shot run)

This folder is a client-facing starter for running one licensed watchlist execution with Docker Compose.

One-command first run (bootstrap + preflight + run + verify), from repo root:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_first_run.js --workspace ./tenants/client-a --tag <TAG> --json

Failure output includes failed_step and remediation_hints for quick triage. Use --diagnostics-bundle-out <path> to persist a support bundle with redacted env + failure context.

Provision tenant-scoped workspace/config templates first:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_provision_client.js --tenant-id client-a --workspace-root ./tenants --json

Or provision directly from issued artifacts to avoid template replacement:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_provision_client.js \
  --tenant-id client-a \
  --workspace-root ./tenants \
  --watchlist ./intake/client-a/watchlist.v0.1.json \
  --license-receipt ./intake/client-a/license_receipt.json \
  --license-public-keys ./intake/client-a/public_keys.json \
  --license-key-rotation-policy ./intake/client-a/key_rotation_policy.v0.1.json \
  --json

Stage and validate incoming license artifacts before cutover:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_rotate_license.js \
  --workspace ./tenants/client-a \
  --incoming-receipt ./intake/client-a/license_receipt.json \
  --incoming-keys ./intake/client-a/public_keys.json \
  --json

Apply rotation when preflight succeeds:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_rotate_license.js \
  --workspace ./tenants/client-a \
  --incoming-receipt ./intake/client-a/license_receipt.json \
  --incoming-keys ./intake/client-a/public_keys.json \
  --apply \
  --json

Rotation records always emit <rotation_record>.sha256; add --signing-key <ed25519_privkey.pem>, --signing-command "<cmd>", PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY, or PATENTCHECKER_SELF_SERVE_OPS_SIGNING_COMMAND for detached signature/pubkey/fingerprint sidecars. For --signing-command, the signer reads PATENTCHECKER_SELF_SERVE_SIGNING_PAYLOAD_B64 and must emit JSON with signature_b64 and signer_pubkey_pem on stdout. Starter bundles include scripts/self_serve_signing_command_template.mjs as a reference signer command implementation. Verify rotation receipts offline with:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_verify_rotation_receipt.js \
  --receipt ./tenants/client-a/license/rotations/license_rotation.<rotation_id>.v0.1.json \
  --require-signed \
  --expected-signer-fingerprint ed25519:<64hex> \
  --json

Export monthly usage + invoice-ready lines for this tenant:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_export_usage_invoice.js \
  --tenant-dir ./tenants/client-a \
  --period-start 2026-02-01T00:00:00Z \
  --period-end 2026-03-01T00:00:00Z \
  --out-dir ./tenants/client-a/billing/exports/2026-02 \
  --json

Deliver the exported invoice artifacts to billing ingest:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_deliver_invoice_export.js \
  --workspace ./tenants/client-a \
  --export-dir ./tenants/client-a/billing/exports/2026-02 \
  --json

Check tenant license renewal lead-time:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_license_status.js \
  --workspace ./tenants/client-a \
  --warn-days 30 \
  --critical-days 7 \
  --json

No-repo bootstrap path:

BashPowerShellPython API (coming)

ogn CLI

mkdir -p ./patentchecker-self-serve-client
cd ./patentchecker-self-serve-client
gh release download <TAG> -R omniscoder/patentchecker-releases \
  -p self_serve_client_starter.v1.zip \
  -p self_serve_client_starter.v1.zip.sha256
sha256sum -c self_serve_client_starter.v1.zip.sha256
unzip -q self_serve_client_starter.v1.zip
node ./scripts/self_serve_provision_client.mjs --tenant-id client-a --workspace-root ./tenants --json

After setting .env and input paths, run:

BashPowerShellPython API (coming)

ogn CLI

node ./scripts/self_serve_first_run.mjs --workspace ./tenants/client-a --no-bootstrap --json

1) Prepare config and inputs

BashPowerShellPython API (coming)

ogn CLI

cp .env.example .env

Then provide these files/paths:

PATENTCHECKER_WATCHLIST_PATH -> your compiled watchlist.v0.1.json
PATENTCHECKER_LICENSE_RECEIPT_PATH -> your issued license_receipt.json
PATENTCHECKER_LICENSE_PUBLIC_KEYS_PATH -> public keys JSON for receipt verification
PATENTCHECKER_RUN_AT -> required for module / http watchlists
PATENTCHECKER_RETAIN_LAST -> required retention window for compose flows (>=1)
PATENTCHECKER_MIN_FREE_MB -> optional output disk headroom floor (512 default, 0 disables)
PATENTCHECKER_MAX_WATCHLIST_BYTES -> optional watchlist size cap in bytes (5242880 default, 0 disables)
PATENTCHECKER_MAX_SEQUENCES -> optional watchlist sequence cap (1000 default, 0 disables)
PATENTCHECKER_MAX_LICENSE_RECEIPT_BYTES -> optional receipt file size cap (262144 default, 0 disables)
PATENTCHECKER_MAX_LICENSE_KEYS_BYTES -> optional keys file size cap (262144 default, 0 disables)
PATENTCHECKER_MAX_LICENSE_KEYS_COUNT -> optional key entry count cap (256 default, 0 disables)
PATENTCHECKER_HTTP_ENDPOINT_POLICY -> optional endpoint lint policy (private-or-https default, https-only strict)
PATENTCHECKER_IMAGE_REF_POLICY -> optional image lint policy (non-floating default, digest-only strict)
PATENTCHECKER_LICENSE_VERIFY_NOW -> optional fixed timestamp for receipt validity checks
PATENTCHECKER_BILLING_ENDPOINT -> optional billing ingest endpoint for invoice delivery
PATENTCHECKER_BILLING_BEARER_TOKEN -> optional bearer token for billing ingest auth
PATENTCHECKER_BILLING_BEARER_TOKEN_FILE -> optional preferred bearer-token file path (owner-only perms on POSIX, e.g. chmod 600)
PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY -> optional Ed25519 private key PEM used to sign rotation receipts and readiness bundles
PATENTCHECKER_SELF_SERVE_OPS_SIGNING_COMMAND -> optional external signer command used to sign rotation receipts and readiness bundles (mutually exclusive with PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY)
PATENTCHECKER_BILLING_TIMEOUT_MS -> optional delivery timeout in milliseconds (20000 default)
PATENTCHECKER_BILLING_ALLOW_HTTP -> optional override (1) for trusted non-https endpoints
PATENTCHECKER_BILLING_DELIVERY_MAX_ATTEMPTS -> optional queue max failed attempts before dead-letter (5 default)
PATENTCHECKER_BILLING_DELIVERY_BASE_BACKOFF_MS -> optional queue base retry backoff in ms (60000 default)
PATENTCHECKER_BILLING_DELIVERY_MAX_BACKOFF_MS -> optional queue max retry backoff in ms (3600000 default)
PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE -> queue/delivery runtime mode (development default in scripts; self-serve default here is production, and doctor fail-closes billing config outside production)
PATENTCHECKER_BILLING_ALERT_WEBHOOK_URL -> optional webhook endpoint for queue incident alerts
PATENTCHECKER_BILLING_ALERT_BEARER_TOKEN -> optional webhook bearer token (mutually exclusive with token-file setting)
PATENTCHECKER_BILLING_ALERT_BEARER_TOKEN_FILE -> optional preferred bearer-token file path for queue incident alerts (chmod 600 on POSIX)
PATENTCHECKER_BILLING_ALERT_TIMEOUT_MS -> optional incident webhook timeout in milliseconds (10000 default)
PATENTCHECKER_BILLING_ALERT_NOTIFY_ON -> optional incident trigger mode (failed-or-dead-letter default; also failed, dead-letter, non-ok, always)
PATENTCHECKER_BILLING_ALERT_ALLOW_HTTP -> optional override (1) for trusted private-host non-https incident webhook endpoints

2) Run preflight checks

From repo root:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_doctor.js --json

self_serve_doctor auto-loads .env from the current directory. To use a different file:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_doctor.js --json --dotenv-file ./path/to/client.env

Preflight also validates watchlist/receipt/keys JSON contract shape before any Docker run. It also lints Ed25519 signature/public-key format (signature bytes + 32-byte key material). For http adapters, it lints endpoint safety (private-or-https by default). It lints image refs (non-floating by default, with optional digest-only strict mode). It enforces watchlist size/sequence guardrails (max_watchlist_bytes, max_sequences). It enforces receipt/keyset size and key-count guardrails (max_license_receipt_bytes, max_license_keys_bytes, max_license_keys_count). It validates billing delivery settings (PATENTCHECKER_BILLING_*) including endpoint policy, bearer token/token-file exclusivity, token-file permission checks, timeout bounds, retry/backoff sanity, and runtime-mode value checks. It enforces retain_last sanity and checks output filesystem free space (min_free_mb). If PATENTCHECKER_LICENSE_VERIFY_NOW is set, it enforces receipt validity at that timestamp.

Optional: export a handoff-ready preflight bundle after checks pass:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_bundle.js --bundle-dir ./self-serve-readiness/client-a --dry-run --json

Add --signing-key <ed25519_privkey.pem> or --signing-command "<cmd>" to include a detached signature over the canonical preflight report. Reference command template: --signing-command "node ./scripts/self_serve_signing_command_template.mjs --key ./keys/ops_rotation_ed25519.pem" Validate the bundle offline with:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_bundle.js verify --bundle-dir ./self-serve-readiness/client-a --json

For signed bundles, pin signer identity:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_bundle.js verify \
  --bundle-dir ./self-serve-readiness/client-a \
  --expected-signer-fingerprint ed25519:<sha256(spki_der)> \
  --require-signed \
  --receipt-out ./self-serve-readiness/client-a.verify_receipt.v0.1.json \
  --json

--receipt-out emits a canonical verification receipt JSON and <receipt>.sha256.

Third parties can validate that receipt artifact directly (without full bundle checks):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_verify_receipt.js \
  --receipt ./self-serve-readiness/client-a.verify_receipt.v0.1.json

Rotation receipt artifacts can be validated independently with:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_verify_rotation_receipt.js \
  --receipt ./tenants/client-a/license/rotations/license_rotation.<rotation_id>.v0.1.json \
  --json

3) Execute one run

For file / file_fixture watchlists:

BashPowerShellPython API (coming)

ogn CLI

docker compose --env-file .env -f examples/self-serve-client/docker-compose.yml up runner_once

For module / http watchlists:

BashPowerShellPython API (coming)

ogn CLI

docker compose --env-file .env -f examples/self-serve-client/docker-compose.yml up runner_once_timed

Outputs are written under PATENTCHECKER_OUT_DIR.

4) Verify output offline

BashPowerShellPython API (coming)

ogn CLI

npm run verify:run -- <run_dir>

Where <run_dir> is the run path printed by the runner summary.

5) Export usage + invoice lines

Portfolio-level export across all tenants under ./tenants:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_export_usage_invoice.js \
  --workspace-root ./tenants \
  --period-start 2026-02-01T00:00:00Z \
  --period-end 2026-03-01T00:00:00Z \
  --pricebook ./billing/pricebook.v0.1.json \
  --json

Export artifacts:

usage_events.v0.1.ndjson
invoice_lines.v0.1.csv
invoice_export.v0.1.json
.sha256 files for all exports
export fail-closes when run_metadata license fields (org_id, sku, license_id, policy_pack) drift from embedded license_receipt.json, when run_metadata.run_timestamp drifts from run_manifest.run.run_at, when run_metadata.pinned_receipt_sha256 drifts from license_receipt.sha256 / license_receipt.summary.json, or when run timestamps fall outside license validity windows

6) Monitor license renewal lead-time

Run per tenant:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_license_status.js \
  --workspace ./tenants/client-a \
  --warn-days 30 \
  --critical-days 7 \
  --json

Optional strict mode for CI/cron checks:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_license_status.js \
  --workspace ./tenants/client-a \
  --warn-days 30 \
  --critical-days 7 \
  --fail-on-warning \
  --json

7) Deliver invoice export to billing sink

Deliver one period to billing ingest (reads PATENTCHECKER_BILLING_* from .env unless flags override):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_deliver_invoice_export.js \
  --workspace ./tenants/client-a \
  --export-dir ./tenants/client-a/billing/exports/2026-02 \
  --json

Add an Ed25519 payload signature:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_deliver_invoice_export.js \
  --workspace ./tenants/client-a \
  --export-dir ./tenants/client-a/billing/exports/2026-02 \
  --signing-key ./keys/billing_delivery_ed25519.pem \
  --json

Rotate billing bearer token file (staged validate, then apply):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_rotate_billing_token.js \
  --workspace ./tenants/client-a \
  --token-file ./tenants/client-a/secrets/billing_ingest.token \
  --incoming-token-file ./intake/client-a/billing_ingest.token \
  --json

node scripts/self_serve_rotate_billing_token.js \
  --workspace ./tenants/client-a \
  --token-file ./tenants/client-a/secrets/billing_ingest.token \
  --incoming-token-file ./intake/client-a/billing_ingest.token \
  --apply \
  --json

Revoke billing bearer token file (archives previous token, then removes active token file):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_rotate_billing_token.js \
  --workspace ./tenants/client-a \
  --token-file ./tenants/client-a/secrets/billing_ingest.token \
  --revoke \
  --apply \
  --json

If PATENTCHECKER_BILLING_BEARER_TOKEN_FILE is set in tenant .env, --token-file can be omitted. Add --signing-key ./keys/ops_rotation_ed25519.pem, --signing-command "<cmd>", PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY, or PATENTCHECKER_SELF_SERVE_OPS_SIGNING_COMMAND to sign billing-token rotation receipts.

Runtime safety note for direct delivery:

PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE=production blocks --allow-http
use development only for tightly controlled maintenance/debug runs

8) Process delivery queue with retry/backoff

Recommended scheduler wrapper for unattended runs (defaults to runtime_mode=production and always enforces strict fail flags):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_billing_queue_scheduler.js \
  --workspace-root ./tenants \
  --tenant-id client-a \
  --env-file ./tenants/client-a/.env \
  --json

self_serve_provision_client also scaffolds tenant-local scheduler artifacts:

./tenants/<tenant-id>/ops/run_billing_queue_scheduler.sh
./tenants/<tenant-id>/ops/systemd/patentchecker-billing-queue-<tenant-id>.service
./tenants/<tenant-id>/ops/systemd/patentchecker-billing-queue-<tenant-id>.timer
./tenants/<tenant-id>/ops/cron/patentchecker-billing-queue.cron

Provisioned ops/run_billing_queue_scheduler.sh runs queue scheduling first, then queue incident alert delivery from latest_run_receipt.v0.1.json.

Process all queued exports across tenants:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_invoice_delivery_queue.js \
  --workspace-root ./tenants \
  --max-attempts 5 \
  --base-backoff-ms 60000 \
  --max-backoff-ms 3600000 \
  --lock-stale-ms 7200000 \
  --run-receipt-out ./tenants/billing_delivery_queue/latest_run_receipt.v0.1.json \
  --metrics-out ./tenants/billing_delivery_queue/latest_metrics.prom \
  --metrics-prefix patentchecker_self_serve_invoice_delivery_queue \
  --json

Target only one tenant:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_invoice_delivery_queue.js \
  --workspace-root ./tenants \
  --tenant-id client-a \
  --json

Strict mode for cron/CI alerting (non-zero exit on failed attempts or dead-letter outcomes):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_invoice_delivery_queue.js \
  --workspace-root ./tenants \
  --tenant-id client-a \
  --fail-on-failed \
  --fail-on-dead-letter \
  --json

Emit queue incident alerts directly from the latest queue run receipt:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_billing_queue_incident_alert.js \
  --workspace-root ./tenants/client-a \
  --env-file ./tenants/client-a/.env \
  --run-receipt ./tenants/client-a/billing_delivery_queue/latest_run_receipt.v0.1.json \
  --json

Retry policy defaults resolve from billing env vars when flags are omitted:

PATENTCHECKER_BILLING_DELIVERY_MAX_ATTEMPTS
PATENTCHECKER_BILLING_DELIVERY_BASE_BACKOFF_MS
PATENTCHECKER_BILLING_DELIVERY_MAX_BACKOFF_MS
precedence: CLI flag > process env > --env-file
use --bearer-token-file (instead of inline --bearer-token) to avoid exposing bearer secrets in process argv
--dry-run simulates queue attempts without mutating per-export queue state (delivery_state, canonical delivery_receipt, or dead-letter artifacts)
--dry-run-retain-attempts prunes older dry-run attempt artifacts per export (200 default, 0 disables pruning)

Queue lock behavior:

default lock file: billing_delivery_queue/invoice_delivery_queue.lock.v0.1.json
stale lock reclaim default: --lock-stale-ms 7200000 (2h)
--lock-stale-ms 0 disables stale reclaim
lock release is ownership-token guarded (a run will not remove a lock file it does not own)
lock metadata redacts --bearer-token and sensitive --header values in lock/run-receipt command fields
--no-lock bypasses lock protection (advanced/manual use only)

Per-export queue artifacts (non-dry-run runs):

delivery_state.v0.1.json (+ .sha256)
delivery/attempts/attempt_XXXX.delivery_receipt.v0.1.json (+ .sha256) on success
delivery/attempts/attempt_XXXX.failure.v0.1.json (+ .sha256) on failure
delivery_dead_letter.v0.1.json (+ .sha256) at max failed attempts

Per-run queue artifacts:

billing_delivery_queue/latest_run_receipt.v0.1.json (+ .sha256) with deterministic queue summary + target details
billing_delivery_queue/latest_metrics.prom (+ .sha256) with Prometheus-compatible queue counters
billing_delivery_queue/alerts/latest_alert_receipt.v0.1.json (+ .sha256) with incident detection/dedupe/webhook delivery result
billing_delivery_queue/alerts/latest_state.v0.1.json (+ .sha256) dedupe state keyed by last notified run receipt hash + notify mode
dry-run attempt receipts in billing_delivery_queue/dry_run_attempts/export_<hash>/attempt_XXXX.{delivery_receipt|failure}.v0.1.json (+ .sha256)