Purpose and access
`/organic-income` and `GET /api/organic-income` provide one editor-only,
aggregate view of the provenance acquisition funnel. The API is private,
`no-store`, and exposes no names, email addresses, provider credentials, or
buyer identifiers. The cockpit never authorizes publication, email, payments,
or commercial terms.
It also reads the signed research approval register and presents its six
dependency-ordered lanes, blockers, and first safe preparation command. The
register is hidden on failed integrity verification and never becomes an
activation control. See
`../research-commons/approval-register.md`(../research-commons/approval-register.md).
Evidence model
The cockpit reads the release-bound launch artifact and, when present, the
latest normalized organic-income report. It verifies the report digest, current
release digest, five provider receipt hashes, export timestamps, and freshness.
Each receipt also retains the SHA-256 of the exact raw CSV or canonical private
ledger input. Retain that source privately under the evidence reference; a hash
without the replayable source is integrity metadata, not attributable evidence.
Evidence older than 35 days is stale. A missing report is unknown, never a
zero. Invalid or release-mismatched evidence cannot populate metrics.
The view covers Search Console and Bing visibility, GA4 landing sessions and
events, checklist downloads, consented and confirmed leads, nurture state,
checkout starts, human-review inquiries, settled orders, gross revenue,
refunds, processor fees, attributable costs, net income, and excluded sandbox
payments.
Research contribution-path choices and downstream expert-review-form opens are
separate aggregate metrics. The latter measures whether the open-review
handoff is being attempted, but it is never interpreted as a submitted review,
qualified researcher, validation, demand, revenue, or income.
The normalized input contract is
`organic-income-export.schema.json`(organic-income-export.schema.json). It
enumerates every accepted aggregate event and the exact Search Console, Bing,
lead-status, and payment row shapes. The runtime importer remains authoritative:
it rejects direct identifiers, unknown or duplicate GA4 events, extra GA4 row
fields, invalid counts, malformed receipts, and non-HTTPS evidence references.
It also requires the exact bundle/source/search/lead/payment fields, unique lead
statuses and settlement IDs, supported payment modes and states, bounded source
labels, valid payment receipt digests, and provider capture timestamps at or
after the measurement window closes. A pre-window export cannot represent a
completed reporting period.
The schema is a preparation aid, not evidence and not an authorization to query
providers or activate analytics, email, or payments.
The expert-review funnel decision joins only integrity-verified aggregate
counts and the signed approval register. It distinguishes unavailable evidence,
no observed interest, contribution interest, form-open interest, and genuine
validation-artifact readiness. Its next actions are limited to refreshing
evidence, improving the approved handoff, inspecting approved return channels,
or accountable human review. It never recommends identifying or contacting a
visitor.
Operator commands
pnpm organic:search-normalize -- --provider=<google-search-console|bing-webmaster-tools> --input=<csv> --indexed-pages=<count> --evidence-ref=<provider-url> --exported-at=<ISO> --window-start=<ISO> --window-end=<ISO> --output=<new-search-fragment.json>
pnpm organic:ga4-normalize -- --input=<ga4.csv> --evidence-ref=<analytics.google.com-url> --exported-at=<ISO> --window-start=<ISO> --window-end=<ISO> --output=<new-ga4-fragment.json>
pnpm organic:leads-normalize -- --input=<private-leads.json> --evidence-ref=<https-url> --exported-at=<ISO> --window-start=<ISO> --window-end=<ISO> --output=<new-lead-fragment.json>
pnpm organic:payments-normalize -- --input=<private-settlements.json> --evidence-ref=<https-url> --exported-at=<ISO> --window-start=<ISO> --window-end=<ISO> --output=<new-payment-fragment.json>
pnpm organic:bundle-assemble -- --search-console=<json> --bing=<json> --ga4=<json> --leads=<json> --payments=<json> --window-start=<ISO> --window-end=<ISO> --days=30|60|90 --output=<new-bundle.json>
pnpm organic:fragment-replay -- --kind=<search-console|bing|ga4|leads|payments> --raw=<retained-file> --fragment=<normalized.json>
pnpm organic:custody-prepare -- --search-console-raw=<file> --search-console-fragment=<json> --bing-raw=<file> --bing-fragment=<json> --ga4-raw=<file> --ga4-fragment=<json> --leads-raw=<private-file> --leads-fragment=<json> --payments-raw=<private-file> --payments-fragment=<json> --window-start=<ISO> --window-end=<ISO> --days=30|60|90 --output=<new-directory>
pnpm organic:income-preflight -- --input=<normalized-export.json> --days=30
pnpm organic:cockpit:report -- --input=<normalized-export.json> --days=30
pnpm organic:cockpit:report -- --input=<normalized-export.json> --days=60
pnpm organic:cockpit:report -- --input=<normalized-export.json> --days=90
pnpm organic:cockpit:browser-proof
The search normalizer is an offline preparation step for exact daily
`Date,Clicks,Impressions` exports from Search Console or Bing. It rejects extra
dimensions, duplicate or out-of-window dates, impossible ratios, non-integer
counts, future/pre-close exports, and non-provider evidence hosts. An explicit
non-negative indexed-page count is required. The command performs no network
request and does not authenticate either the CSV or page count.
The GA4 normalizer is an offline preparation step for a filtered aggregate
export containing exactly `Event name` and `Event count`. It accepts only the
funnel event allowlist, refuses dimensions, unknown or duplicate events,
invalid counts, future timestamps, non-Analytics evidence hosts, and output
overwrite. Its JSON fragment can populate the bundle's `ga4` field, but it is
not provider authentication or accepted evidence and performs no network call.
The lead normalizer is the sensitive-input boundary. It accepts only known
encrypted lead-store fields plus `lead_id`, `status`, and `updated_at`, rejects
plaintext or unknown fields, duplicate IDs, unsupported states, future exports,
and updates after capture. Pending, confirmed, and suppressed rows respectively
require consented, confirmed, and suppressed event timestamps inside the exact
half-open reporting window before aggregation.
No identifier, hash, token, ciphertext, or contact field reaches its fragment or
console summary; input remains local and the output path cannot be overwritten.
The payment normalizer is the accounting-input boundary. It accepts an exact
local settlement-ledger shape, requires explicit lowercase `usd` input and emits
explicit `USD`, and rejects unknown or identifying fields, duplicate settlement
IDs, unsupported modes/states, invalid receipt hashes, negative or impossible
amounts, non-settled settlement timestamps, future exports, and updates after
capture. Every normalized row carries `recognizedAt`: settled rows use
`settled_at`; other states use `updated_at`. Recognition must fall inside the
exact half-open reporting window. It performs no provider query, cannot overwrite output, and cannot
establish that a receipt is genuine; retained attributable provider receipts and
the later evidence verifier remain authoritative.
Settled movements contribute gross and order count. Refunded/disputed movements
must carry zero gross plus positive refund recognition and still contribute
period fees/costs; pending movements must recognize no money. This permits a
refund-only period to report negative net income without inventing a sale.
Every fragment now carries `windowStart`, `windowEnd`, and `inputSha256`; the importer requires
all five to match the bundle exactly. The bundle assembler removes the final
five-file hand-edit. It derives the
current release, joins the local fragments, reruns the full privacy, structure,
chronology, uniqueness, and period preflight, then writes only a new path. Its
console summary exposes only digests and row counts. It never queries providers,
accepts evidence, or treats a bundle as validation, demand, revenue, or income.
Search/GA4 hash exact CSV bytes; lead/payment lanes hash a deterministic
canonical form of the private rows. The digest propagates into the signed source
receipt without exposing the raw rows.
The fragment replay command reruns the lane-specific normalizer against one
retained raw file and requires byte-for-byte canonical equality with the full
normalized fragment. It writes nothing and reports only lane, digests, row
count, and false authority. Lead/payment rows and identifiers never appear in
its success summary. Replay proves transformation integrity, not provider
authenticity, attribution, demand, revenue, or income.
The custody-preparation command makes that replay all-or-nothing across all five
lanes. It validates every raw/fragment pair and the exact-release bundle before
creating the output directory, then writes only the normalized bundle and a
privacy-safe custody manifest. The manifest retains raw/fragment digests, row
counts, release/window/report/bundle bindings, and false authority—not evidence
URLs, raw rows, identifiers, or provider credentials. Existing output paths are
refused and a validation failure creates no directory.
Run the preflight first. It checks the complete runtime contract, exact current
Research Commons release, and reporting-period length, then prints only a
digest and source-row counts. It writes no report and does not expose provider
references or row contents. The report command reruns this same preflight
against the retained launch release before replacing any evidence artifact. The
standalone income-report writer also binds the current Research Commons
manifest and requires `--days`; neither writer accepts a future-dated provider
export.
The input window must exactly equal the selected period. Outputs are written to
`artifacts/organic-income/reports/` with provider source hashes and a report
digest. Never use synthetic exports as production evidence. Browser proof checks
authenticated desktop/mobile privacy, unknown semantics, alerts, accessibility,
and overflow without changing an external system.
Alert response
a historical comparison.
and suppression handling.
gates; the cockpit is not an activation control.
- `measurement.missing`: import a complete provider window.
- `measurement.invalid`: regenerate from retained normalized exports.
- `release.digest-mismatch`: use current-release evidence or explicitly declare
- `measurement.stale`: refresh all provider exports before deciding.
- `indexing.none`: inspect robots, canonical, sitemap, exclusion, and crawl evidence.
- `conversion.checklist-zero`: verify analytics delivery and the checklist CTA.
- `delivery.unverified`: disable sends and prove confirmation, bounce, unsubscribe,
- `settlement.none`: reconcile pending/failed payments and provider settlements.
- `nurture.disabled` and `checkout.disabled`: follow their separate approval
The canonical documentation contract is `docs/` Markdown rendered through
`/docs`, `/api/docs/manifest`, and `/api/docs/content`.