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 onboarding

BioCost quickstart Docs overview Benchmark pack Example pipelines GitHub

Self-Serve Client Onboarding

Goal: let a client run PatentChecker in their own environment with no live support.

This guide is execution-focused:

prepare inputs (watchlist.v0.1.json, license_receipt.json, public_keys.json)
run automated preflight checks
execute one run
verify output offline
export tenant usage + invoice lines
monitor license renewal lead-time
deliver invoice export to billing sink
process delivery queue with retry/backoff + incident alerting

Prerequisites

Docker Engine + Docker Compose plugin
Access to a PatentChecker image (ghcr.io/omniscoder/patentchecker:<tag-or-digest>)
A signed license receipt and matching public key set
A compiled watchlist JSON (watchlist.v0.1.json)

0) Provision tenant workspace (recommended)

Scaffold a tenant-scoped workspace with prewired .env, compose file, and input templates:

BashPowerShellPython API (coming)

ogn CLI

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

This creates ./tenants/client-a/ with tenant-scoped config and a TENANT_SETUP.md runbook. Replace inputs/watchlist.v0.1.json, license/license_receipt.json, and license/public_keys.json before first production run. self_serve_doctor now fail-closes if provisioning placeholders remain (TODO*, REPLACE_WITH_*, zeroed hashes, .example endpoint stubs).

For direct provisioning with issued artifacts (no template replacement step), seed inputs during provisioning:

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

0b) Intake and rotate issued license artifacts (recommended)

Validate new receipt/key artifacts via staged preflight 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 only after validation passes:

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 writes a machine-readable record under license/rotations/ and keeps prior artifacts in license/archive/<rotation_id>/. Rotation records always emit <rotation_record>.sha256; when --signing-key, --signing-command, PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY, or PATENTCHECKER_SELF_SERVE_OPS_SIGNING_COMMAND is configured they also emit detached Ed25519 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 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

If you are rotating the invoice export key-rotation policy at the same time, include the policy artifact in both validate/apply commands:

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 \
  --incoming-license-key-rotation-policy ./intake/client-a/key_rotation_policy.v0.1.json \
  --json

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 \
  --incoming-license-key-rotation-policy ./intake/client-a/key_rotation_policy.v0.1.json \
  --apply \
  --json

Quick path (one command)

From this repo (or a starter bundle that includes scripts/self_serve_first_run.mjs), run:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_first_run.js \
  --workspace ./tenants/client-a \
  --tag <TAG> \
  --diagnostics-bundle-out ./tenants/client-a/diagnostics/first-run.diagnostics.v0.1.json \
  --json

This command performs bootstrap, preflight, one compose run, and offline verification in sequence. On failure, the JSON error payload includes failed_step and remediation_hints.

1) Initialize the client starter

Use examples/self-serve-client/:

BashPowerShellPython API (coming)

ogn CLI

cp examples/self-serve-client/.env.example .env

No-repo bootstrap path (download starter asset from public releases):

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 updating .env and input paths, execute the full first-run workflow:

BashPowerShellPython API (coming)

ogn CLI

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

Update .env values:

PATENTCHECKER_IMAGE
PATENTCHECKER_WATCHLIST_PATH
PATENTCHECKER_OUT_DIR
PATENTCHECKER_LICENSE_RECEIPT_PATH
PATENTCHECKER_LICENSE_PUBLIC_KEYS_PATH
PATENTCHECKER_LICENSE_KEY_ROTATION_POLICY_PATH (optional; JSON policy used by invoice export to enforce signer key_id rotation windows)
PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY (optional; Ed25519 private key PEM used to sign self_serve_rotate_license, self_serve_rotate_billing_token, and self_serve_bundle)
PATENTCHECKER_SELF_SERVE_OPS_SIGNING_COMMAND (optional; external signer command for self_serve_rotate_license, self_serve_rotate_billing_token, and self_serve_bundle; mutually exclusive with PATENTCHECKER_SELF_SERVE_OPS_SIGNING_KEY)
PATENTCHECKER_RUN_AT (required for module / http watchlists)
PATENTCHECKER_RETAIN_LAST (required for env-file/compose flows; set an integer >= 1)
PATENTCHECKER_MIN_FREE_MB (optional; default 512, set 0 to disable)
PATENTCHECKER_MAX_WATCHLIST_BYTES (optional; default 5242880, set 0 to disable)
PATENTCHECKER_MAX_SEQUENCES (optional; default 1000, set 0 to disable)
PATENTCHECKER_MAX_LICENSE_RECEIPT_BYTES (optional; default 262144, set 0 to disable)
PATENTCHECKER_MAX_LICENSE_KEYS_BYTES (optional; default 262144, set 0 to disable)
PATENTCHECKER_MAX_LICENSE_KEYS_COUNT (optional; default 256, set 0 to disable)
PATENTCHECKER_HTTP_ENDPOINT_POLICY (optional; private-or-https default, https-only for strict TLS)
PATENTCHECKER_IMAGE_REF_POLICY (optional; non-floating default, digest-only for immutable pinning)
PATENTCHECKER_LICENSE_VERIFY_NOW (optional; enforce receipt validity window at a fixed timestamp)
PATENTCHECKER_BILLING_ENDPOINT (optional; billing ingest URL used by invoice delivery command)
PATENTCHECKER_BILLING_BEARER_TOKEN (optional; bearer token for billing endpoint auth; mutually exclusive with PATENTCHECKER_BILLING_BEARER_TOKEN_FILE)
PATENTCHECKER_BILLING_BEARER_TOKEN_FILE (optional; preferred file path for bearer token secret; keep owner-only permissions, e.g. chmod 600; mutually exclusive with PATENTCHECKER_BILLING_BEARER_TOKEN)
PATENTCHECKER_BILLING_TIMEOUT_MS (optional; delivery timeout in milliseconds, default 20000)
PATENTCHECKER_BILLING_ALLOW_HTTP (optional; set 1 only for trusted private-host non-https endpoints)
PATENTCHECKER_BILLING_DELIVERY_MAX_ATTEMPTS (optional; queue max failed attempts before dead-letter, default 5)
PATENTCHECKER_BILLING_DELIVERY_BASE_BACKOFF_MS (optional; queue base retry backoff in ms, default 60000)
PATENTCHECKER_BILLING_DELIVERY_MAX_BACKOFF_MS (optional; queue max retry backoff in ms, default 3600000)
PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE (queue/delivery default is development; set production for billing workflows, and self-serve templates default this to 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 PATENTCHECKER_BILLING_ALERT_BEARER_TOKEN_FILE)
PATENTCHECKER_BILLING_ALERT_BEARER_TOKEN_FILE (optional; preferred file path for webhook bearer token, owner-only perms on POSIX, e.g. chmod 600; mutually exclusive with PATENTCHECKER_BILLING_ALERT_BEARER_TOKEN)
PATENTCHECKER_BILLING_ALERT_TIMEOUT_MS (optional; incident webhook timeout in milliseconds, default 10000)
PATENTCHECKER_BILLING_ALERT_NOTIFY_ON (optional; incident trigger mode: failed-or-dead-letter default, failed, dead-letter, non-ok, always)
PATENTCHECKER_BILLING_ALERT_ALLOW_HTTP (optional; set 1 only for trusted private-host non-https webhook endpoints)

2) Run preflight checks

Run 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 when present. If your env file is somewhere else, pass it explicitly:

BashPowerShellPython API (coming)

ogn CLI

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

self_serve_doctor validates:

required files and writable output directory
watchlist contract shape (schema_name/schema_version/watchlist_id/sequences/adapter.kind)
watchlist size guard (max_watchlist_bytes)
watchlist sequence-count guard (max_sequences)
receipt file-size guard (max_license_receipt_bytes)
keyset file-size guard (max_license_keys_bytes)
keyset count guard (max_license_keys_count)
run_at requirement for module / http adapters
retention value sanity (retain_last >= 1 for env-file/compose self-serve runs)
output disk headroom check (min_free_mb threshold on output filesystem)
HTTP endpoint lint policy for http adapters (scheme + host scope)
billing endpoint lint policy + billing bearer token/token-file exclusivity + token-file permission checks + billing retry/backoff/runtime-mode sanity checks
image reference lint policy (non-floating or digest-only)
license receipt contract shape + timestamps + validity-window bounds
optional receipt validity check at --now / PATENTCHECKER_LICENSE_VERIFY_NOW
signature format lint (ed25519, detached signature bytes)
license keys shape, key strength (32-byte Ed25519 public keys), and presence of receipt signature.key_id
optional key-rotation policy contract + runtime signer key_id allowlist checks (PATENTCHECKER_LICENSE_KEY_ROTATION_POLICY_PATH) when configured
Docker binary and daemon access
image health (patentchecker info)
receipt verification (patentchecker license verify)

If checks pass, the output includes recommended_run_command.

http adapter endpoint policy defaults to private-or-https:

https:// is always accepted
http:// is accepted only for private hosts (for example adapter, localhost, RFC1918 IPs)
public hosts over http:// fail preflight

Set PATENTCHECKER_HTTP_ENDPOINT_POLICY=https-only (or pass --http-endpoint-policy https-only) to require https:// for every http adapter endpoint.

Billing endpoint preflight defaults to https-only:

https:// billing endpoints pass by default
http:// billing endpoints fail unless PATENTCHECKER_BILLING_ALLOW_HTTP=1
even with PATENTCHECKER_BILLING_ALLOW_HTTP=1, public hosts over http:// still fail (private-or-https guard)
queue retry policy is linted so PATENTCHECKER_BILLING_DELIVERY_MAX_BACKOFF_MS must be >= PATENTCHECKER_BILLING_DELIVERY_BASE_BACKOFF_MS
billing-configured preflight requires PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE=production (doctor fail-closes otherwise)

Container image policy defaults to non-floating:

digest-pinned refs (...@sha256:<digest>) pass
explicit version-style tags (...:v0.1.33) pass
floating tags like :latest fail preflight

Set PATENTCHECKER_IMAGE_REF_POLICY=digest-only (or pass --image-ref-policy digest-only) to require digest-pinned images for every run.

Retention and disk safety defaults:

set PATENTCHECKER_RETAIN_LAST to keep only the most recent N runs (self-serve starter default: 30)
preflight enforces free-space minimum using PATENTCHECKER_MIN_FREE_MB (default 512)
set PATENTCHECKER_MIN_FREE_MB=0 only if you intentionally want to disable disk-headroom checks

Input guardrail defaults:

preflight enforces PATENTCHECKER_MAX_WATCHLIST_BYTES=5242880 (5 MiB)
preflight enforces PATENTCHECKER_MAX_SEQUENCES=1000
preflight enforces PATENTCHECKER_MAX_LICENSE_RECEIPT_BYTES=262144 (256 KiB)
preflight enforces PATENTCHECKER_MAX_LICENSE_KEYS_BYTES=262144 (256 KiB)
preflight enforces PATENTCHECKER_MAX_LICENSE_KEYS_COUNT=256
set any guardrail value to 0 only if you intentionally want to disable that guardrail

If you set PATENTCHECKER_LICENSE_VERIFY_NOW (or pass --now), preflight also enforces that the receipt is valid at that timestamp before any Docker run.

2b) Export a readiness bundle (recommended for handoff)

After preflight passes, generate a tamper-evident handoff artifact:

BashPowerShellPython API (coming)

ogn CLI

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

Optional signing with key file (Ed25519 private key PEM):

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_bundle.js \
  --bundle-dir ./self-serve-readiness/client-a \
  --signing-key ./keys/ed25519_privkey.pem \
  --dry-run --json

Bundle outputs include:

MANIFEST.v0.1.json (hash-indexed bundle manifest)
preflight_report.v0.1.json (canonical preflight payload)
inputs/ copies of watchlist/receipt/public keys used for preflight
optional signatures/ files when --signing-key or --signing-command is used
deterministic ZIP + .sha256 (unless --no-zip is set)

Reference signer command: --signing-command "node ./scripts/self_serve_signing_command_template.mjs --key ./keys/ops_rotation_ed25519.pem"

Verify the bundle offline before distribution or execution:

BashPowerShellPython API (coming)

ogn CLI

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

If you sign bundles, pin the expected 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 writes a canonical verification receipt JSON plus <receipt>.sha256 for procurement/compliance evidence.

For external parties who only need to validate receipt integrity (without running full bundle verification), use:

BashPowerShellPython API (coming)

ogn CLI

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

Optional SHA pinning:

BashPowerShellPython API (coming)

ogn CLI

node scripts/self_serve_verify_receipt.js \
  --receipt ./self-serve-readiness/client-a.verify_receipt.v0.1.json \
  --expected-sha256 sha256:<64hex> \
  --json

No-repo handoff path (download from release assets):

BashPowerShellPython API (coming)

ogn CLI

gh release download <TAG> -R omniscoder/patentchecker-releases \
  -p self_serve_verify_receipt_standalone.v1.zip \
  -p self_serve_verify_receipt_standalone.v1.zip.sha256 \
  -p self_serve_verify_rotation_receipt_standalone.v1.zip \
  -p self_serve_verify_rotation_receipt_standalone.v1.zip.sha256
sha256sum -c self_serve_verify_receipt_standalone.v1.zip.sha256
sha256sum -c self_serve_verify_rotation_receipt_standalone.v1.zip.sha256
unzip -q self_serve_verify_receipt_standalone.v1.zip
unzip -q self_serve_verify_rotation_receipt_standalone.v1.zip
node self_serve_verify_receipt.mjs --receipt ./self-serve-readiness/client-a.verify_receipt.v0.1.json
node self_serve_verify_rotation_receipt.mjs --receipt ./tenants/client-a/license/rotations/license_rotation.<rotation_id>.v0.1.json --json

3) Execute one licensed 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 (requires PATENTCHECKER_RUN_AT):

BashPowerShellPython API (coming)

ogn CLI

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

Runner output prints a JSON summary that includes run_id and run path under PATENTCHECKER_OUT_DIR.

4) Verify run output offline

BashPowerShellPython API (coming)

ogn CLI

npm run verify:run -- <run_dir>

verify:run never requires a license and can be repeated at any time.

5) Export usage metering + invoice-ready lines

Export one tenant’s monthly usage for invoicing:

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 \
  --license-key-rotation-policy ./tenants/client-a/license/key_rotation_policy.v0.1.json \
  --out-dir ./tenants/client-a/billing/exports/2026-02 \
  --json

Portfolio-level export across every tenant 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

Optional rotation policy contract:

{
  "schema_name": "patentchecker.license_key_rotation_policy",
  "schema_version": "0.1",
  "overlap_starts_at": "2026-02-01T00:00:00.000Z",
  "unknown_key_denied_after": "2026-03-01T00:00:00.000Z",
  "min_overlap_days": 7,
  "overlap_allowed_key_ids": ["lic_k1_2026q1", "lic_k2_2026q2"],
  "allowed_key_ids": ["lic_k2_2026q2"]
}

Outputs include:

usage_events.v0.1.ndjson (one metering event per run in period)
invoice_lines.v0.1.csv (invoice-ready line items by tenant/org/sku/tier/policy pack)
invoice_export.v0.1.json (period summary + totals + line items)
.sha256 hash files for every export artifact
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, when run timestamps fall outside license validity windows, or when signer key_id violates configured rotation policy overlap/cutover allowlists

6) Monitor license renewal lead-time

Check one tenant’s active license window and renewal risk:

BashPowerShellPython API (coming)

ogn CLI

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

For strict automation (fail CI/cron when warning threshold is reached):

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

Status classes: valid, warning, critical, expired, not_yet_valid. Default fail mode is invalid_only (non-zero exit only for expired / not_yet_valid).

7) Deliver invoice export to billing sink

Send one exported period to your billing endpoint:

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

Use file-based bearer auth (preferred over inline secrets):

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 \
  --bearer-token-file ./secrets/billing_ingest.token \
  --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.

To add an Ed25519 payload signature for downstream verification:

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

Outputs include:

delivery_receipt.v0.1.json
delivery_receipt.v0.1.json.sha256

Runtime safety note:

PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE=production blocks --allow-http in direct delivery runs (set development only for controlled maintenance/debug sessions)

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 discovered invoice exports (tenant scan) with retry/backoff and dead-letter handling:

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 one tenant explicitly:

BashPowerShellPython API (coming)

ogn CLI

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

For strict automation (exit non-zero when failures or dead-letter events occur in a run):

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

Queue retry policy resolution (when flags are omitted):

reads PATENTCHECKER_BILLING_DELIVERY_MAX_ATTEMPTS, PATENTCHECKER_BILLING_DELIVERY_BASE_BACKOFF_MS, and PATENTCHECKER_BILLING_DELIVERY_MAX_BACKOFF_MS
precedence: explicit CLI flag > process environment > --env-file
set PATENTCHECKER_BILLING_DELIVERY_RUNTIME_MODE=production (or pass --runtime-mode production) to fail-close risky queue flags (--allow-http, --no-lock, --force)
use --bearer-token-file (instead of inline --bearer-token) to avoid exposing bearer secrets in process argv (owner-only perms required; chmod 600)
--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 defaults:

queue runs acquire billing_delivery_queue/invoice_delivery_queue.lock.v0.1.json to prevent overlapping cron execution
stale lock reclaim defaults to --lock-stale-ms 7200000 (2h)
set --lock-stale-ms 0 to disable 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
use --no-lock only for advanced/manual debugging where overlapping runs are controlled externally (blocked when runtime_mode=production)

Queue artifacts written per export directory (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) once max failed attempts are reached

Queue-run artifacts written per queue execution:

billing_delivery_queue/latest_run_receipt.v0.1.json (+ .sha256) summarizing attempted/skipped/dead-letter outcomes
billing_delivery_queue/latest_metrics.prom (+ .sha256) with Prometheus-compatible gauges for discovered, attempted, delivered, failed, dead-lettered, and skipped counts
billing_delivery_queue/alerts/latest_alert_receipt.v0.1.json (+ .sha256) summarizing 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 under billing_delivery_queue/dry_run_attempts/export_<hash>/attempt_XXXX.{delivery_receipt|failure}.v0.1.json (+ .sha256)

Optional: compile watchlist from YAML + TSV

If the client authors watchlists in YAML:

BashPowerShellPython API (coming)

ogn CLI

patentchecker watchlist compile \
  --spec watchlist.yaml \
  --sequences sequences.tsv \
  --out watchlist.v0.1.json

Use the output path as PATENTCHECKER_WATCHLIST_PATH.