Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / company-monitoring-intelligence

Company monitoring intelligence

Company Monitoring turns account-owned company records into source-grounded material event intelligence. It links each company to bounded identity claims, gathers evidence from approved providers, checks attribution and impact, and exposes only results that meet coverage and trust rules. The capability is account scoped and currently remains behind independent rollout gates; its contract defines the product shape before the web, alert, and write surfaces are enabled. See Intelligence products for the wider product model.

Product role

Company Monitoring answers a focused question: what important event affects a company that the customer follows? It is different from the broader public company intelligence tools described in Intelligence briefs and analysis. Those tools resolve public companies and filings. Company Monitoring follows a customer-owned portfolio and must avoid turning weak identity matches into company facts.

The product keeps four ideas separate:

  • Identity: which company a source may describe.
  • Evidence: what a provider observed and where it came from.
  • Material impact: whether the occurrence matters to the company and through which channel.
  • Coverage: whether the system searched enough to support an event or a quiet result.

This separation lets a reader see “no event found,” “the search was incomplete,” and “the company identity is not resolved” as different outcomes.

Intelligence boundary

The monitored record is private to an account. The account supplies the company portfolio, while the system supplies provider evidence, source checks, classification, and current event state. Access is derived from the current entitlement on each use, and the monitoring account is provisioned when an authenticated feature entry point first uses it. A material event is a company-specific view of a neutral occurrence, so one occurrence can have different impacts for different companies.

The public contract supports these product actions:

Audience needProduct result
Build a portfolioCreate, import, update, pause, or remove monitored companies
Review current stateList companies with lifecycle and coverage state
Scan new intelligenceList current company impacts with direction and lifecycle filters
Follow changesPoll a signed change cursor and resnapshot when its generation is old
Inspect evidenceOpen one event with its company impact and bounded source references
Judge search qualityRead provider coverage, observation state, and assessment readiness

The service is account scoped and derives the account from trusted server context. It does not accept an account identifier as a client-owned routing field. Read and write actions use separate company_monitoring:read and company_monitoring:write scopes. The current rollout keeps the REST write, publication, UI, and alert flags disabled, so these contracts are not a promise that every surface is live.

References: proto/…/service.proto• L10-65 proto/…/coverage.proto• L23-34 shared/company-monitoring-contract.ts• L37-52 convex/…/productCatalog.ts• L1-80 convex/…/companyMonitoringAccountLifecycle.test.ts• L98-116 convex/…/companyMonitoringApiKeys.test.ts• L20-41

Product relationships

Company Monitoring is one branch of the intelligence product chain. It starts with a customer-selected company rather than a global feed, then joins provider observations to identity claims before it produces an impact record. Its result can support a later brief or analyst view, but it does not replace the broader brief, forecast, or resilience products described in Forecasting, scenarios, and resilience.

The relationship is:

flowchart LR
    A[Customer company record] --> B[Identity claims]
    B --> C[Provider observations]
    C --> D[Coverage and evidence]
    D --> E[Claim and impact assessment]
    E --> F[Admitted company impact]
    F --> G[Portfolio and change views]
    F --> H[Brief or decision context]

The result remains bounded and source-linked. It reports direction, impact channel, magnitude, confidence axes, and event lifecycle rather than presenting a free-form model answer as fact.

References: proto/…/company_monitoring.proto• L254-313 proto/…/service.proto• L133-193 shared/company-monitoring-evidence.ts• L335-362

Company records and claims

The portfolio record is the customer’s control point for monitoring. It names the company, records its domicile, and holds the claims that providers may use to find and attribute evidence. A record has an active, paused, or removed lifecycle. Removal is terminal and starts bounded cleanup of the company’s private monitoring data.

Portfolio records

A monitored company is not the same as a provider identity. The company row is the stable customer object. Provider identities and evidence can change as accounts are reassigned, claims expire, content is deleted, or a source loses authority.

The record supports a bounded set of identity inputs:

  • Name and aliases.
  • Official domains.
  • Legal identifiers.
  • X account IDs and handles.
  • Locations and a customer reference.

Creation starts the first source work. A change to the name, claims, or lifecycle advances the company snapshot and causes active source work to be cancelled or rescheduled. This prevents a scan for an old identity from publishing against the new record.

References: proto/…/company_monitoring.proto• L167-220 convex/…/companies.ts• L42-69 convex/…/companies.ts• L187-339 convex/…/companies.ts• L343-422

Claim trust policy

A claim is one independently trusted fact about a company. Trust belongs to the claim, not to the whole company. Each claim has provenance, a trust state, allowed uses, and an optional expiry.

Allowed use limits what the claim can do:

Claim useMeaning
DiscoveryThe claim may help a provider find candidate material
AttributionThe claim may help bind a source to this company
Primary evidenceThe claim may support first-party evidence under the provider rules

Customer-entered claims can support discovery and, for selected identity types, attribution. They do not become primary evidence merely because a customer entered them. Provider-backed identity checks must earn stronger authority. For example, an X identity needs a current independently supported domain binding and a matching handle before it can support authoritative first-party evidence.

Claims can expire or become rejected. When that happens, stored evidence is rechecked and may lose authority. The system then recomputes the related occurrence instead of keeping an old attribution alive.

References: proto/…/company_monitoring.proto• L22-49 shared/company-monitoring-contract.ts• L133-204 convex/…/_shared.ts• L104-158 convex/…/orchestration.ts• L872-981 convex/…/evidence.ts• L582-684

Coverage and observation states

Coverage describes the quality of the search. Observation describes what the search found. The system does not use an incomplete search to claim that a company was quiet.

The main states are:

StateMeaning
Awaiting first scanNo complete first search exists
Identity unresolvedNo independent identity binding supports the provider search
AdequateRequired provider work is fresh, complete, and not capped
Partial or staleSome evidence exists, but the search cannot support a full conclusion
UnavailableProvider or source work failed
Needs confirmationThe available identity or evidence needs customer review

An observation may say that events were found, that no events were observed, or that the result is unknown. no_events_observed is valid only with adequate, fresh, uncapped coverage from the required providers. identity_unresolved therefore cannot appear as a quiet result.

References: proto/…/company_monitoring.proto• L82-116 shared/company-monitoring-contract.ts• L511-558 convex/…/orchestration.ts• L1622-1651 tests/company-monitoring-contract.test.mts• L704-784

Signal processing and admission

The monitoring pipeline converts provider results into evidence, groups evidence into occurrences, and asks a classifier to describe the occurrence. A deterministic admission policy then decides whether to publish, hold, reject, or expire it. The classifier supplies an assessment; it does not set the product rules.

Provider scans

The system schedules bounded scans for the enabled providers. Convex selects an account and a fixed company cohort, creates a time window and query version, and gives the worker a lease. The worker has no tenant target of its own. It executes only the work that Convex selected and returns a bounded receipt.

The two provider paths have different roles:

  • Exa supplies public discovery candidates. Its results remain low authority until company claims support a stronger attribution.
  • X supplies recent-search content and identity observations. First-party use depends on a current authoritative identity and the permitted storage and use rules.

Provider results can be complete, partial, capped, malformed, or failed. A non-reassuring receipt preserves that condition and schedules the next scan without treating the result as a valid quiet observation.

References: convex/…/orchestration.ts• L274-460 convex/…/orchestration.ts• L1046-1147 convex/…/orchestration.ts• L1417-1604 convex/…/orchestration.ts• L2140-2297

Evidence normalization

Evidence normalization binds each provider row to a company through direct verification or claim matching. It records the provider, source, matched claims, authority, independence, time, and stable fingerprints. Content from the same occurrence is grouped so repeated or syndicated copies do not look like separate independent events.

The selection policy ranks evidence by source authority, independence, and time. It keeps a bounded reference set for classification and records whether references were truncated. An occurrence becomes a pending candidate only when evidence exists. If all active evidence expires, is deleted, becomes unavailable, or loses authority, the candidate is recomputed and its observation block is removed or terminalized.

References: shared/company-monitoring-evidence.ts• L46-108 shared/company-monitoring-evidence.ts• L243-362 shared/company-monitoring-evidence.ts• L365-477 convex/…/evidence.ts• L167-357

Claim and impact assessment

The classifier describes three separate truth axes: attribution, occurrence, and material impact. It also provides direction, affected channels, magnitude, a neutral summary, and evidence-backed rationales. Each axis must cite evidence from the candidate’s selected reference set.

The admission policy applies the product decision after output validation:

  1. Reject a wrong-company, false, or immaterial result.
  2. Hold an uncertain result, weak axis, conflicting evidence, or insufficient source authority for a later retry.
  3. Expire a held candidate after its retry window ends.
  4. Publish only when the confidence floors and source authority rules pass.

Overall confidence is the minimum of the three confidence axes. A published impact keeps its event revision and impact revision. Later evidence can correct or retract it, but a retracted impact cannot be re-admitted by a normal state transition.

References: scripts/…/company-monitoring-classification.mjs• L22-40 scripts/…/company-monitoring-classification.mjs• L72-126 scripts/…/company-monitoring-classification.mjs• L407-433 scripts/…/company-monitoring-classification.mjs• L483-613 shared/company-monitoring-contract.ts• L222-240 shared/company-monitoring-contract.ts• L378-421

Admission records

Admission records make each decision reviewable. They retain the evidence revision, selected evidence fingerprints, policy and model versions, confidence floors, query versions, decision, and reason codes. A lease fence and replay digest prevent an old worker or a repeated submission from changing a newer decision.

Evidence changes invalidate the model-visible snapshot. A worker that returns after the snapshot changes cannot finalize against the new candidate. A held decision is retried only while its evidence and account scope remain valid.

References: convex/…/admissionSnapshot.ts• L6-55 convex/…/admission.ts• L60-212 convex/…/admission.ts• L273-394 convex/…/admission.ts• L398-622

Audience workflows

Company Monitoring serves a private portfolio workflow rather than a public feed. A customer first establishes a monitored company, then reads coverage and event state, and finally follows changes through a snapshot-safe cursor. External agents can use the same account-scoped contract when access is granted.

Portfolio management

A customer or account tool can create one company or import a bounded batch. The first authenticated company action provisions the monitoring account; a billing entitlement write alone does not. A scoped Company Monitoring API key is another first-use entry point, while an unscoped key does not create monitoring state. Normalization makes names, domains, handles, claims, and import identity stable before the system computes replay fingerprints. Repeating the same request is therefore a replay or no-op rather than a second company.

The lifecycle supports active, paused, and removed states. Pausing stops new scan work while retaining the portfolio record. Removing cancels work, deletes claims, and schedules bounded cleanup for scan state, evidence, admission records, and provider-specific data. Entitlement access is rechecked on every read, write, and key operation, so an expired entitlement is denied before the periodic reconciler runs. The reconciler later moves stale accounts to lapse and starts bounded cleanup; a renewal can restore the same portfolio before destructive purge, but owner or account deletion is terminal.

References: proto/…/portfolio.proto• L9-111 shared/company-monitoring-contract.ts• L239-324 convex/…/companies.ts• L100-153 convex/…/companies.ts• L393-533 convex/…/accounts.ts• L432-584 convex/…/companyMonitoringAccountLifecycle.test.ts• L135-171 convex/…/companyMonitoringAccountLifecycle.test.ts• L217-321 convex/…/companyMonitoringAccountLifecycle.test.ts• L698-807

Event reading

Readers use a snapshot boundary for portfolio and impact lists. The boundary gives the reader a generation and an opaque signed cursor. The cursor is bound to the account, filters, surface, mode, expiry, and snapshot generation, so a client cannot reuse it for another account or silently continue across a changed snapshot.

Change polling reports whether the current cursor is still valid. When the generation changes, the client must resnapshot before it continues. Event detail returns the neutral event, the company-specific impact, and a bounded evidence list. This gives a reader both the current interpretation and the source trail behind it.

References: proto/…/events.proto• L9-97 shared/company-monitoring-contract.ts• L560-674 proto/…/company_monitoring.proto• L276-313

Agent and product access

The account-scoped Company Monitoring service is designed for product clients and external tools that already have an approved account context. It separates read access from write access and returns access state, portfolio count, limit, snapshot generation, and independent feature flags. API keys with Company Monitoring scopes carry the exact monitoring-account binding; validation fails closed when the account is stale, missing, or no longer entitled. Cache invalidation is best effort for the control path, but a malformed or incomplete cache response is treated as an error rather than as successful invalidation.

The existing get_company_intelligence MCP tool is a separate public-company tool. It resolves SEC identity and public filings by ticker or name. It must not be treated as a Company Monitoring portfolio reader, because it does not carry the customer’s private account scope or monitored-company lifecycle.

References: proto/…/service.proto• L10-65 shared/company-monitoring-contract.ts• L41-55 proto/…/coverage.proto• L23-34 api/…/company-intel-tools.ts• L103-122 convex/…/companyMonitoringApiKeys.test.ts• L43-70 convex/…/companyMonitoringApiKeys.test.ts• L211-226

Offline evaluation

Offline evaluation measures whether Company Monitoring can find, attribute, and classify useful material events before live publication. It keeps source identities and labels private from policy authors and model runs, then compares versioned predictions with sealed labels through deterministic score rules.

Curated evidence corpus

Curators research candidate private companies and occurrences from public evidence. A curation manifest records company identity, private status, occurrence identity, source authority, chronology, and syndication. Included candidates receive opaque example IDs. Excluded candidates retain only an exclusion reason.

The compiler validates the manifest before it removes raw identities. It rejects missing provenance, invalid time order, duplicate content, duplicate occurrences, duplicate source origins, and missing primary evidence. Separate pilot, tracer, and Stage 3 corpora must not overlap on occurrence, content, corporate family, or source origin.

Gold labels then mark publication eligibility, materiality, direction, and customer usefulness. Customer usefulness stays unknown until an approved external-customer judgment exists; an internal analyst cannot substitute for that judgment.

References: shared/company-monitoring-curation.ts• L18-125 shared/company-monitoring-curation.ts• L381-575 shared/company-monitoring-curation.ts• L590-705 shared/company-monitoring-curation.ts• L711-757 scripts/company-monitoring-curation.mts• L13-24

Blind prediction runs

The offline prediction run uses a locked corpus and sealed provider observations. It checks that corpus, curation, query, policy, model, provider, and runtime versions match before it classifies any example. Provider receipts and custody fields show that the run used a complete, bounded observation set without exposing labels to the classifier.

The run records latency and cost as well as the prediction. Authenticated checkpoints allow a stopped run to resume without changing completed rows. A signed prediction bundle carries the prediction set and a receipt that binds it to the protocol, corpus, curation, provider observations, and classifier runtime.

References: shared/company-monitoring-offline-prediction-contracts.ts• L3-26 shared/company-monitoring-offline-prediction-contracts.ts• L48-116 shared/company-monitoring-offline-predictions.ts• L384-720 shared/company-monitoring-offline-predictions.ts• L849-998 scripts/company-monitoring-offline-predictions.mts• L188-303

Evaluation gates

The evaluation engine has a staged gate. Stage 0 checks the frozen protocol, empirical base rate, rediscovery, historical usefulness, provider policy, cost package, chronology, and artifact schemas. It remains separate from later admission metrics so the system does not claim viability from synthetic arithmetic alone.

Later blind scoring reports publication material-impact precision, company attribution precision, direction accuracy overall and by direction, confidence calibration, discovery, latency, and cost. It returns pass, fail, or incomplete. A denominator shortfall can continue only through a signed, precommitted expansion that preserves the earlier scored rows. Stage 4 is explicitly outside this release input.

The checked-in runtime gate is currently STOP. The live worker keeps classifier credentials inert until the approved protocol and independent threshold anchors permit a deliberate rollout.

References: shared/company-monitoring-evaluation.ts• L24-59 shared/company-monitoring-evaluation.ts• L469-576 shared/company-monitoring-evaluation.ts• L741-772 shared/company-monitoring-evaluation.ts• L1094-1150 shared/company-monitoring-blind-evaluation.ts• L116-160 shared/company-monitoring-blind-evaluation.ts• L936-1144 scripts/company-monitoring-blind-evaluation.mts• L193-228 scripts/company-monitoring-worker.mjs• L40-45

Automation lifecycle

Automation joins durable account state with provider work and admission work. Convex owns the schedule, lease, replay fence, evidence revision, and receipt. An always-on worker supplies provider access and execution time, but it cannot choose a tenant or bypass the account and policy checks.

Scan and admission cycle

Each active company has provider obligations. The scheduler groups obligations into bounded cohorts and recurring time windows. The worker claims one due item, executes the selected provider, and finalizes the result before the lease expires. A complete receipt rearms the next scan; a non-reassuring receipt records why the result cannot support a quiet assessment.

Admission follows a second leased cycle. The worker claims one pending candidate with an evidence revision, calls the classifier only when the runtime gate allows it, and sends the untrusted output back to Convex. Convex validates the output and applies the deterministic policy. A lease expiry, changed evidence revision, inactive account, or changed model binding fences the result.

References: convex/…/orchestration.ts• L1046-1147 convex/…/orchestration.ts• L1150-1237 convex/…/orchestration.ts• L2186-2297 convex/…/admission.ts• L273-394 convex/…/admission.ts• L398-505

Worker health and recovery

The Railway worker runs continuously and polls Convex. Each poll checks scan work, then admission work when the classifier is enabled. It reports scan and admission health as separate subsystems, with claim failures carrying bounded transport details and the last healthy scan time. Redis stores only short-lived health metadata; it is not part of work selection or finalization. Provider credentials can be present before rollout, but the checked-in classifier runtime gate keeps live model calls disabled.

The workflow is safe to retry. A crashed worker leaves an expired lease that Convex can reclaim. A late finalize is fenced. A repeated finalize with the same replay identity returns the prior result. Account, company, evidence, and provider purges run in bounded batches so cleanup can continue after a transaction or process limit.

References: scripts/company-monitoring-worker.mjs• L1-15 scripts/company-monitoring-worker.mjs• L40-45 scripts/company-monitoring-worker.mjs• L121-169 scripts/company-monitoring-worker.mjs• L402-685 scripts/company-monitoring-worker.mjs• L687-724 convex/…/companies.ts• L426-533 convex/…/accounts.ts• L432-584

Rollout controls

Provider scans, publication, REST writes, the UI, alerts, and classifier admission use independent flags. This prevents a partial rollout from exposing a reader before the data and policy path are ready. A provider also needs the current claim policy migration before it can create new work. The worker accepts no tenant target: Convex selects the account and work, while the worker only executes the leased item.

The system records query, policy, source, evidence-selection, retry, model, and runtime versions with the work or decision. A policy or model change therefore has a visible version boundary instead of silently mixing results from different rules.

References: proto/…/company_monitoring.proto• L328-336 convex/…/orchestration.ts• L215-237 scripts/…/company-monitoring-classification.mjs• L22-40 convex/…/admission.ts• L121-129 scripts/company-monitoring-worker.mjs• L43-45 scripts/company-monitoring-worker.mjs• L727-790 tests/company-monitoring-contract.test.mts• L367-389

Change checklist

When these files or sections are changed, remember to consider these:

  • When a claim type, allowed use, trust state, or expiry rule changes, align the public contract, normalization, provider identity checks, evidence revalidation, and admission authority rules.
  • When coverage or observation states change, keep the quiet-result guard aligned with provider completeness, identity resolution, API filters, and client polling behavior.
  • When evidence selection or classifier-visible fields change, rotate the evidence snapshot policy and keep candidate revisions, leases, replay fences, and decision provenance aligned.
  • When an impact field or lifecycle changes, update the neutral event, company impact, detail evidence, list filters, change cursor, and correction or retraction rules together.
  • When a provider query, result cap, storage rule, or scan window changes, update the Convex obligation shape, worker executor, finalization validator, coverage receipt, and recurring work identity.
  • When the evaluation protocol, corpus, labels, or classifier runtime changes, invalidate the linked digests and keep pilot, tracer, Stage 3, continuation, and bundle checks on the same version set.
  • When rollout flags change, verify that access state, worker admission, publication, REST writes, UI, and alerts do not expose a downstream surface before its required inputs are ready.
  • When entitlement or API-key access changes, keep first-use provisioning, per-call entitlement checks, account binding, cache invalidation, reconciler behavior, and purge fencing aligned.

Important failure modes

TriggerConsequenceGuard
A company has no current independent identity bindingA provider search can miss the company or attach another company’s content.Set identity_unresolved; do not report no_events_observed.
A customer claim is treated as primary evidenceCustomer input can be mistaken for independent proof.Keep allowed uses explicit and require provider-specific authority for primary evidence.
A provider returns a capped, partial, malformed, or failed resultThe portfolio can look quiet even though the search was incomplete.Store a non-reassuring receipt and expose partial, stale, unavailable, or unknown coverage.
Billing writes provision or revoke monitoring state directlyA payment retry or entitlement change can create state outside the authenticated access path or race with the reconciler.Provision on authenticated first use and let the reconciler converge stale accounts.
A scoped API key has no active account bindingA credential can reach a portfolio without a valid account or remain usable after access ends.Bind the key to the exact account and fail closed on missing, stale, or expired account state.
Evidence changes after a classifier lease is issuedA result for old evidence can be published against a new company view.Bind the lease to the evidence revision and candidate evidence snapshot digest.
Model output cites foreign evidence or violates its schemaThe system can publish an unsupported claim or malformed impact.Validate exact fields and evidence IDs; invalid output becomes a reject decision.
A source loses authority after admissionAn old event can keep using a claim that is expired or rejected.Revalidate claims, mark evidence authority loss, and recompute the occurrence.
A worker finalizes after its lease expires or after another worker owns the workA stale worker can overwrite newer provider or admission state.Use lease tokens, worker identity, evidence revisions, and fencing checks.
Offline labels, predictions, or corpus versions do not matchA score can compare different populations or rule versions.Require digests and version equality; stop on membership, custody, or chronology mismatch.
A scored corpus lacks a required denominatorA passing rate can look strong because hard cases are missing.Return incomplete and allow continuation only through a signed precommitted expansion.
Credentials exist while the approved runtime gate is STOPA provisioned worker can make unapproved live classifier calls.Keep the classifier runtime disabled until the independent approval and threshold checks pass.

Key files

FileWhy to read it
proto/…/company_monitoring.protoDefines the product vocabulary for companies, claims, coverage, evidence, events, impacts, confidence, and rollout flags.
proto/…/service.protoShows the account-scoped read and write surface and its access split.
shared/company-monitoring-contract.tsDefines normalized portfolio input, claim use, confidence, lifecycle, coverage, and cursor rules.
convex/…/companies.tsShows portfolio lifecycle, replay behavior, rescheduling, and bounded removal cleanup.
convex/…/evidence.tsShows evidence normalization, occurrence grouping, authority loss, expiry, and candidate recomputation.
shared/company-monitoring-evidence.tsDefines source matching, authority, independence, fingerprinting, ranking, and candidate projection.
scripts/…/company-monitoring-classification.mjsDefines the classifier output shape and the deterministic publish, hold, reject, and expire policy.
convex/…/admission.tsShows leased candidate admission, evidence snapshot checks, decision records, retry, and fencing.
convex/…/orchestration.tsShows provider scheduling, cohort work, provider receipt validation, recurring scans, and finalization.
scripts/company-monitoring-worker.mjsShows the always-on provider and admission control loop, separate subsystem health, retry-safe finalization, and rollout gate.
convex/…/companyMonitoringAccountLifecycle.test.tsShows first-use provisioning, immediate entitlement denial, reconciliation, renewal, bounded purge, terminal deletion, and owner-fence rotation behavior.
convex/…/companyMonitoringApiKeys.test.tsShows scoped-key provisioning and account binding, fail-closed validation, and Redis cache invalidation guards.
shared/company-monitoring-curation.tsDefines the private-evidence curation manifest, opaque corpus compilation, gold labels, and split disjointness.
shared/company-monitoring-offline-predictions.tsShows version-locked offline observations, checkpoints, reconciliation, prediction bundles, and continuation.
shared/company-monitoring-blind-evaluation.tsDefines blind forecasts, score reports, admission metrics, calibration, and fail-closed evaluation rules.
scripts/company-monitoring-blind-evaluation.mtsShows the evaluation CLI and its distinction between engine errors and a gate that did not pass.
scripts/company-monitoring-offline-predictions.mtsShows offline preflight, prediction execution, sealed output, and authenticated recovery commands.
api/…/company-intel-tools.tsClarifies the separate public-company intelligence tool so it is not confused with private portfolio monitoring.