[research·M2·deferred] User-defined condition lookup adapters for metrics the kernel does not know how to query

[atomchung]

Status

Research / Discussion only — deferred. Do not implement inside #403's first rationale-memory vertical slice.

Owner direction, 2026-07-31:

Condition monitoring should eventually support a lookup interface the user knows how to use even when FOMO Kernel does not know that metric or source in advance.

This issue owns the adapter/contract question only. #403 continues to own PositionRationale; #412/#430 continue to own condition semantics and checks; #432 continues to own the separate problem of turning a vague value judgment into something observable.

Milestone

M2 — Recall and Compare My Reasons, later capability after the direct rationale → next-review slice is accepted.

This is not on the #610 acceptance path and not an active implementation front.

User outcome

A user can define a condition whose data lives behind a source or interface FOMO Kernel does not natively understand, for example:

• a private company KPI dashboard;
• a local CSV or spreadsheet export;
• an authenticated API;
• a database/view exposed by the user's own host;
• a custom script or MCP/tool that returns one bounded observation.

The user or host supplies how to obtain the observation. FOMO Kernel stores the condition and a stable reference to the configured lookup, later receives one normalized observation, and performs the comparison/adjudication through the existing deterministic condition machinery.

Example:

User: "If internal weekly activation falls below 42%, I want to revisit this thesis."
Host-configured lookup: private_metrics.weekly_activation(company="ACME")
Normalized observation: {value: 39.8, unit: "%", period: "2026-W31", as_of: "2026-07-31", source_ref: "private_metrics:weekly_activation:v1"}
Kernel: compares 39.8 against 42 and records the check; it never learns the API secret or invents the metric definition.

Current behavior / evidence

The current condition-slot contract assumes the agent can freeze a neutral query, obtain an observation, and classify the source as derived, fetched, researched, or unmapped.

That covers public lookups and engine-owned metrics, but not a reusable source the user knows and the kernel does not:

• there is no durable source/adapter identity;
• there is no capability declaration describing input/output, authorization or freshness;
• secrets have no explicit ownership boundary;
• the next check cannot deterministically invoke the same private lookup;
• a host can hand in an observation ad hoc, but the kernel cannot distinguish a configured recurring source from one-off prose.

The honest current floor remains unmapped or currently blind. Do not claim monitoring merely because the user named an interface in conversation.

Problem and consequence

Without a bounded adapter contract, one of two bad outcomes occurs:

1. FOMO Kernel rejects useful user-known metrics simply because they are not in its built-in catalog; or
2. an agent improvises calls, credentials, parsing and metric meaning in prose, producing a non-replayable monitor whose result cannot be audited or safely repeated.

The product should be extensible at the observation boundary without becoming a research terminal, generic ETL system, credential store or arbitrary-code runner.

Decision frame

1. Kernel owns the normalized observation contract, not data acquisition

The deterministic core may consume a normalized result such as:

• metric/source identity and version;
• subject/instrument identity when applicable;
• value or event outcome;
• unit and comparison semantics;
• period / document identity;
• as_of and recorded_at;
• source/provenance reference;
• lookup run identity and status;
• explicit unavailable | unauthorized | malformed | stale | ambiguous failure state.

It must not own provider-specific credentials, browser automation, SQL dialects, arbitrary API schemas or private repository traversal.

2. The host/user owns the adapter and secrets

A configured host may expose a named capability such as:

lookup_ref = "private_metrics.weekly_activation:v1"

The capability returns the kernel's normalized observation envelope. Tokens, passwords, cookies, database credentials and private raw payloads stay outside the canonical FOMO Kernel store.

3. No arbitrary executable payload in canonical memory

Do not persist free-form Python, shell, SQL or JavaScript and execute it later from the condition row.

The durable condition stores a typed lookup_ref plus bounded parameters approved by that adapter. The host resolves the reference. Unknown, missing or changed adapters fail closed and leave the condition recorded but unmonitored for that check.

4. User-defined does not mean user-declared truth

The user may define which metric/source matters. The adapter result still needs provenance, time/period identity, type validation and deterministic comparison.

A user saying "the metric is 39%" is a user report, not equivalent to an authenticated adapter observation unless explicitly labelled as such.

5. One adapter can serve multiple conditions; one condition freezes its meaning

A condition must freeze the metric definition, unit, parameters and comparison at creation/revision time. A later adapter implementation change cannot silently alter what an old condition meant.

Version the lookup_ref or its capability contract. Material metric-definition changes require a new condition revision.

Questions to research before implementation

1. Discovery/configuration: how does a host advertise available lookup capabilities without making FOMO Kernel scan all installed tools?
2. Invocation boundary: does the kernel emit a lookup request envelope for the host to fulfill, or may a trusted local adapter be invoked directly?
3. Schema: what is the smallest normalized observation/failure envelope reusable across numeric and event conditions?
4. Authorization: how does the user approve a capability once without exposing secrets to the kernel or asking every review?
5. Freshness and periods: how are repeated reads of the same period deduplicated, and how is genuinely new evidence distinguished from a rewritten source?
6. Idempotency/provenance: what identities make retries converge while preserving distinct observations?
7. Availability: what receipt is shown when the adapter is missing, unauthorized, stale, malformed or returns an ambiguous unit/subject?
8. Portability: what survives export to another host where the adapter is unavailable?
9. Privacy: which metadata may be stored locally, and which raw payloads/secrets must never enter sessions, exports or public QA evidence?
10. Tool ecosystems: can a thin MCP/tool capability contract satisfy this without coupling the kernel to one agent framework?

Scope

• Define a host-neutral, local-first adapter/capability contract for condition observations.
• Define the normalized observation and failure envelope consumed by existing condition checks.
• Define stable/versioned lookup_ref semantics and bounded parameters.
• Define authorization, privacy, portability, replay and unavailable-adapter behavior.
• Prototype with fictional/local adapters only after the research decision is approved.
• Ensure a writer ships with a named future check/reader; no configured source that is never invoked.

Non-goals

• No universal financial-data platform or provider registry.
• No crawler, filing warehouse, news/KOL database or research terminal.
• No arbitrary-code execution from stored condition rows.
• No credential or secret storage in the FOMO Kernel canonical root.
• No silent private-repository reading.
• No automatic invention of a metric for vague statements; [design·P2·parked] The user's reason cannot always be falsified — turning a value judgment into something checkable #432 owns that separate clarification problem.
• No background scheduler, push notification or always-on daemon in the first version.
• No provider-specific implementation inside [feat·M2] Append-only rationale refresh anchored to a position cycle #403.
• No claim that every user-defined metric is trustworthy merely because an adapter returned it.

Acceptance criteria for a future first slice

• A fictional host advertises one versioned lookup capability without the kernel knowing its provider implementation.
• A user creates a condition referencing that capability and bounded parameters.
• The host returns one normalized numeric or event observation with provenance and period/time identity.
• Existing deterministic condition logic performs the comparison; the adapter does not supply the verdict.
• Exact retry is idempotent; a new period or materially changed observation is distinct.
• Missing/unauthorized/stale/malformed/ambiguous adapters fail closed and visibly report recorded but not monitored this check.
• Export preserves the condition and opaque lookup reference without exporting credentials or private raw payloads.
• Import on a host lacking the adapter preserves the condition but does not claim monitoring.
• Public fixtures, logs and QA receipts contain only fictional source names, values and credentials.
• The first owner-live trajectory proves the user can configure a source they know, receive a real later check, and understand the failure state when that source becomes unavailable.

Dependencies

• [feat·M2] Append-only rationale refresh anchored to a position cycle #403 — PositionRationale and optional invalidation wording; does not wait for this issue.
• [feat·design·P1] The observable catalog is closed — user-meaningful conditions need slots, agent adjudication, and two-sided reasoning #412 / PR feat(engine): store the condition the engine cannot compute as a slot (refs #412) #430 — condition-slot and deterministic check semantics.
• [design·P2·parked] The user's reason cannot always be falsified — turning a value judgment into something checkable #432 — vague/unfalsifiable reason clarification; separate upstream problem.
• [safety·M1] Production provenance gate for decision-surface answers #414 — provenance labelling for agent/public claims.
• [arch·M2] Canonical bounded execution-qualified self-report history #450 — bounded self-report reader; not an adapter owner.
• [research·roadmap] Staged direction: pre-trade challenge → decision memory → rule learning #475 — product scope and thin host-adapter boundary.
• [design·M1] Bounded market-context lookup — verify why-now without inventing the user's motive #601 / [architecture·implementation] One market-data resolver — minimum Yahoo calls, one fact bundle for prepare and consider #605 — nearby bounded lookup and market-data abstraction lessons; do not merge this into market-price retrieval.

Privacy boundary

Local-first. Real private metric names, endpoint URLs, account identifiers, queries, tokens, credentials, raw payloads and internal values must not enter the public repository, public issue evidence or committed fixtures.

The canonical store may retain only the minimum local metadata required for replay/audit: opaque adapter identity/version, bounded non-secret parameters, normalized observation, provenance class and failure status. Secrets remain with the host/adapter.

Rollout / compatibility / recovery

Legacy conditions without a lookup_ref remain valid. An unavailable adapter never deletes or rewrites the condition; it yields an explicit failed check and can recover when the capability returns.

Adapter version changes do not reinterpret historical observations. A material definition change creates a new condition revision. Rollback removes invocation support but leaves conditions and historical normalized observations exportable and readable.

Stop condition

Stop after the contract and one fictional end-to-end adapter prove that a user-known source can produce a replayable condition check without moving credentials, arbitrary code or provider-specific acquisition into the kernel. Do not continue into a general plugin platform or background monitoring service.