The Shipping Signal and its agent

Written 2026-09-18 against the platform as it runs. This is a plan for what to build and in which order, grounded in what already exists. Nothing here is implemented unless a section says so.

The thesis it serves: HEY detects meaningful builder activity, corroborated and sourced, before the market necessarily notices it. The subscriber decides what to do with that. A commit alone is nothing. Market data is context. Execution, if it ever exists, lives somewhere the research engine cannot reach.

1. What exists today, and what is reused

Everything a first version needs is already a table, a job or a service. The plan adds one signal kind, one rules table, one chat registry, one delivery sink and one comparison read. It adds no second copy of anything that exists.

Production coverage that bounds a first version (2026-09-17 readings): 4,720 published projects; 1,493 verified builders, of which 1,411 rest on commit summaries, 246 have a release and 82 a follow-up deployment; 2,909 weekly commit summaries all carrying contributor counts, 920 carrying day-by-day commits (every new one since 2026-09-17); 14,270 signals, 15 of 20 kinds having fired; 2 watchlists and 0 confirmed email addresses; 1 API key, unused.

2. The Meaningful Shipping Signal

2.1 What it says

One sentence, always with the reasons: "Project X shipped something meaningful this week from a corroborated repository, and its activity accelerated against its own last 30 days." It is a signal kind, shipping_meaningful, in the existing engine — a new SignalKindSpec in vocabulary.ts and a new pure rule in rules.ts. Not a new table.

2.2 Inputs, and what each is worth today

Every input is a fact HEY already stores. The column on the right is the honest coverage, so the model is weighted by what can carry weight.

2.3 The rule, as a gate and a score

The rule is a gate first and a score second. A project that fails a gate gets no signal, whatever its score — that is what stops a burst of commits from being a signal.

Gates (all must hold):

1. Published, approved, not demo (PUBLISHED_SCOPE).
2. At least one meaningful ship in the last 7 days from a source that is corroborated (context_only = false) and not DISCOVERED-only.
3. At least two distinct kinds of building in the last 30 days, at least one of them not CODE_ACTIVITY (the Under the Radar rule, reused).
4. The repository is not marked fork or template.
5. Activity accelerated: meaningful ships in the last 30 days ≥ 1.5 × the 30 before, or the first release or deployment the project has ever recorded.

Score (0–100, explained component by component, stored with the signal):

Not in the score, by rule: price, market cap, liquidity, volume, holders. They are filters a subscriber applies afterwards (§5), and context the alert carries. The neutrality test that fences signals and radar from the economy (packages/domain/src/hey/neutrality.test.ts) fences this too.

2.4 Why this signal fired — the explanation

The alert never says score = 87. It says what the score is made of, with the sources:

Shipping signal · Quorum · 74/100
Why: 3 kinds of work in 30 days (release, code, docs) · 2.6× the ships of the prior 30 days
· 3 contributors this week · release v0.9.1 on 12 Sep · repository corroborated by the site
Sources: github.com/…/releases/tag/v0.9.1 · code-activity 2026-W37 · docs commit 2026-09-14
Not counted: 41 commits on a repository HEY holds as context (declared by a listing, never
corroborated)

The "not counted" line is mandatory: it is how a subscriber sees the gate working, and how a project learns what would make its activity count.

2.5 Storage

• The signal row: signals with kind = 'shipping_meaningful', importance = score / 100, before_value / after_value = ships in the two windows, evidence[] = the ship URLs, and a metadata JSON with every component and the reasons above. The dedupe key is shipping_meaningful:<project>:<ISO week>, so a project signals at most once a week.
• The comparison read: a new scoreHistoryFor(projectId, windows) over project_scores and builder_score_days returning HBM, contributors and ships at 24 h / 7 d / 30 d / 90 d — the Q1 "comparative windows" item, exposed as /api/projects/{slug}/history.
• The contributor series: a project_code_weeks (project_id, iso_week, commits, active_days, contributors, repositories, censored) table, written by the same CODE_ACTIVITY path that writes the evidence row. Counts only; no login is ever stored.

3. Manipulation, and what stops it

4. The Shipping Signal Agent (Telegram)

4.1 Position

An alert channel for a signal that already exists, in HEY's own words, with four buttons. It computes nothing. It is positioned as a Builder Signal Agent, never as a pump bot: it reports building, it carries the market and risk context beside it, and it never says "buy".

4.2 Flow

signal engine (hourly)            existing
   → shipping_meaningful row      §2
   → SubscriptionMatcher          new: which chats asked for this project/kind/threshold
   → subscriber rules             new: thresholds, filters (§5)
   → delivery ledger              reuse MailDeliveryLedger shape: claim → send → settle
   → TelegramSink                 reuse, one sendMessage per delivery
   → the message                  project · token · what changed · sources · confidence ·
                                  shipping score · market context · risk context ·
                                  [VIEW RESEARCH] [WATCH] [PAPER TRADE] [BUY ELSEWHERE]

BUY ELSEWHERE is a link to the venue, never an action HEY performs, until §6 exists — and then only in a mode the subscriber chose.

4.3 Binding a chat

The mail pattern, reused: a signed, expiring token (issueMailToken-style, action = 'telegram') shown on the account page; the subscriber sends /start <token> to the bot; the bot's inbound webhook resolves the token, stores the chat as a digest (hashFeedToken-style; the chat id is recoverable only through the bot's own lookup), and writes telegram_chats (user_id, chat_digest, chat_ref_encrypted, confirmed_at, revoked_at). /stop revokes. One account may bind several chats; one chat binds to one account.

Inbound is a Telegram webhook route under apps/web/src/app/api/telegram/webhook with the bot secret header checked, rate-limited, and accepting exactly /start, /stop, /watch <slug>, /rules, /help. Nothing else is parsed.

4.4 Subscriptions and rules

signal_subscriptions (id, user_id, channel: 'telegram' | 'webhook' | 'mail', target_ref, scope: { projects?: slug[], narratives?: slug[], kinds?: kind[] }, rules: jsonb, mode: 'alert' | 'paper', created_at, paused_at).

Rules the subscriber can set (each optional; absent means no filter):

• minScore (0–100), minConfidence (the confidence component), minContributors, requireRelease, requireDeployment, minProjectAgeDays
• minLiquidityUsd, minVolume24hUsd, marketStatus (e.g. only ACTIVE_MARKET), maxTop10SharePct, requireVerifiedToken, excludeSharedDeployer, excludeProxy
• allow / block lists of slugs, cooldownHours per project, dailyMax alerts

Rules are evaluated against the signal's stored context at delivery time. They filter; they cannot change the signal's score or its text. The context they read is exactly the set in §5.

4.5 Delivery guarantees

• Idempotent: signal_deliveries (subscription_id, signal_id) unique; a retry never sends twice.
• Ordered per chat; a chat that blocked the bot is paused, not retried forever.
• Rate-limited per Telegram's own limits; the sink already backs off.
• Every delivery carries the signal id, so a later correction (a retracted ship, a demoted repository) can be followed by a correction message to the same chat — the record is kept, and the withdrawal is said out loud.

4.6 Paper trading

A ledger, not a broker: paper_positions (subscription_id, project_id, token, opened_at, opened_price_usd, size_usd, rule_snapshot, closed_at, closed_price_usd). Opened by the subscriber's rules when a signal passes them in paper mode, priced from HEY's own token_market_days close (never a live quote), closed by the subscriber or by a rule (holdDays, takeProfitPct, stopLossPct). A weekly message reports the ledger honestly, including the signals the rules skipped and what those did. This is how a strategy is judged before it costs anything.

5. Risk filters available today

Each is a stored field with the coverage it has; a rule that names a filter with no reading for the token is unmet, not passed.

What a subscriber cannot filter on today, because HEY does not hold it: token age for the 99% of tokens with no pool or creation date; holder concentration for 81% of published tokens; anything cross-chain.

6. Optional execution — isolated by construction

Not built, and not to be built until alert-only and paper trading have run for a quarter. When it is, the shape is fixed now so nothing built before it has to move:

• A separate service (apps/executor, its own container, its own database or schema, its own secrets) that holds the only keys. The research engine, the signal worker and the web app have no network route to it and no credential for it.
• One-way data flow. The executor reads signals and subscriptions through the public API with a key like any other client. It writes nothing HEY reads except an execution ledger the account page displays.
• Per-subscriber limits, enforced in the executor, not in the signal: max position size, max slippage, daily exposure, cooldown, allow and block lists, and a hard cap on total open exposure. A rule the executor cannot verify from its own reading is a refusal.
• Modes: alert-only (default, forever), paper, manual confirmation (the subscriber presses confirm on a message that quotes the limits), auto (opt-in per subscription, per project, with an expiry).
• Kill switch: a single flag in the executor's own settings, flipped by an admin action that writes an audit row, that turns every mode into alert-only within one tick; a second, independent switch is the revocation of the executor's API key on the HEY side, which stops it reading signals at all.
• A compromised signal worker cannot trade. It can only write signals; the executor applies the subscriber's own limits to every signal, and a burst of signals hits the daily exposure cap. A compromised executor cannot forge a signal, because it has no write path into HEY.
• Explainable, twice. Every execution ledger row carries the signal id and its explanation, and the subscriber's rule snapshot that admitted it.

7. Build order

1. Q4 — corroboration hardening the signal reads: scheduled fork re-check, the reviewer surface for held matches, project flags, repo↔contract linkage, project_code_weeks, fingerprinting, first_seen_public_at.
2. Q1 — shipping_meaningful kind and rule with the explanation; scoreHistoryFor and /api/projects/{slug}/history; signals in watchlist updates and the digest; a signals feed and MCP tool; signal_subscriptions with webhook and Telegram alert-only delivery through the ledger.
3. Q2 — the bot: chat binding, rules, the four-button message, paper trading, corrections.
4. Q3 — hosted MCP, structured feeds, agent watchlists; execution only after the quarter of alert-only and paper results is published on the site.

8. What was found while auditing, beyond the ask

• Three of the five signal kinds that have never fired are history-depth problems, not rule problems: usage_broadened (contract callers have three days of history), concentration_rose (holder summaries kept fourteen days, most tokens one day), contract_upgraded (one proxy exists).
• 6,921 of 14,270 signal rows belong to projects outside the published scope and are invisible on every surface; scope is applied at read time, never at write time.
• The Builder Radar's 30-day comparison cannot return anything until the table is 30 days old (it is five).
• Of the four benefits promised to $HEY holders, one has been exercised (the holders-first claim window). The monthly vote has never had a round; the API tiers have one unused key; early access guards zero research notes.
• Reviewer throughput, not token design, is the binding constraint on the research economy: five bounty submissions unreviewed since 2026-09-12, two bond refunds due since the same day.