What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	14841
title	F3 demo reach metrics: falsifiable stranger counts
state	Closed
labels	enhancementaitestingarchitecture
assignees	[]
createdAt	Jul 5, 2026, 11:13 AM
updatedAt	3:43 PM
githubUrl	https://github.com/neomjs/neo/issues/14841
author	neo-gpt
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	3:43 PM
milestone	v13.2

F3 demo reach metrics: falsifiable stranger counts

Closed Backlog/active-chunk-4 enhancementaitestingarchitecture

neo-gpt commented on Jul 5, 2026, 11:13 AM

Context

The v13.2 ROADMAP release gate says every flagship demo reports measured reach: strangers counted, not developers. Parent ticket #14782 names this as F3, and #14790 makes it the Phase-0 launch gate: instrument before announcing anything.

This ticket is the narrow F3 leaf. It exists because #14782 is correctly marked not-code-ready as a bundled measurement umbrella: F1 now has the J2 operator-run leaf (#14840), F2 belongs to the fresh-install / TTFP harness family, and F3 still needs its own reach-metric contract.

The goal is not a new business-dashboard epic and not a Fleet Manager or dock implementation lane. This consumes the shipped business metric schema from #14442/#14446 and pins the per-demo measurement contract that future demo surfaces must satisfy before public launch.

Live latest-open sweep: checked the latest 20 open issues at 2026-07-05T09:13:06Z; no equivalent F3 leaf found. Exact GitHub searches for "F3 demo reach metrics", "falsifiable stranger counts", "demo reach contract", "developer-filter", and "falsifying-query-carrying reach metric" found #14782/#14790 only as parent/adjacent gates. A2A in-flight sweep: latest 30 all-status messages checked at the same boundary; no competing F3 reach-metrics claim. KB/resource sweep found #14782, #14790, #14781, #14789, #14442, and #14446 as adjacent authority, not an equivalent leaf.

The Problem

A demo can ship, get praised by maintainers, and still tell us nothing about whether strangers cared. The ROADMAP explicitly rejects that failure mode: reach must be measured, public claims must carry provenance, and developer-circle traffic must not be counted as traction.

Today the parent artifacts state the requirement but do not define the per-demo contract:

What stable demo identity is measured.
Which view / interaction events count.
How developer/internal traffic is filtered without leaking private data.
Which METRIC node identity and falsifyingQuery reproduce the count.
Which launch/release artifact cites the measured value.

Without this leaf, #14790 Phase 0 remains a slogan: "instrument first" with no concrete surface that can fail closed.

The Architectural Reality

ROADMAP.md names the traction guardrail: measurable reach categories, Ring-0 / analytics-first, strangers counted rather than developers.
#14782 F3 says flagship demos emit Ring-0 events and each has a falsifying-query-carrying reach metric before announcement.
#14790 Phase 0 says every demo surface emits events with the developer-filter documented before launch motion begins.
#14442 defines the business-engine boundary: metric categories can be public; specific targets, revenue, strategy, and client specifics stay private.
#14446 shipped the BUSINESS_GOAL / METRIC schema and read-only probe discipline. ai/graph/businessSchema.mjs requires claimClass, falsifyingQuery, windowSemantics, confoundDisclaimer, and strict boolean publicFlag; validateMetricProperties() fails closed on missing identity fields, non-finite values, and missing falsifyingQuery.
ROADMAP explicitly says no new #14442 leaves for this release path; the CEO-dashboard slice stays gated on #14422. This ticket therefore defines a release-gate metric/readback contract, not a new dashboard surface.

Structure-map gate: ran npm run --silent ai:structure-map -- --files --loc; relevant owning folders include ai/graph, ai/services/graph, ai/services/github-workflow, ai/services/ingestion, demo/app surfaces, and release-note content surfaces.

The Fix

Define the F3 per-demo reach contract and keep it fail-closed until concrete demo surfaces exist:

Give every flagship demo a stable public demo id / surface key before instrumentation.
Define the minimal event envelope for view and meaningful-interaction events. The envelope must be privacy-bounded and must not carry private targets, revenue data, client specifics, or raw identity data.
Map each demo's counted reach into METRIC nodes using the existing business schema. The metric identity must be deterministic, and every published value must carry the falsifyingQuery that reproduces included/excluded counts.
Document the developer-filter heuristic in the metric properties / evidence artifact. The filter can classify maintainers, localhost/dev/test sources, and known internal channels as excluded categories, but public artifacts must not expose private identifiers.
Produce the release/launch evidence line consumed by #14790 and v13.2 release notes: metric id, window, value, falsifying query, confound disclaimer, and provenance.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Flagship demo id / surface key	ROADMAP + #14782 F3 + #14790 Phase 0	Every measured demo has a stable public key used by events and metrics	No stable key => demo cannot be announced as measured	Demo ticket / release-gate note	Static key registry or issue-body row
Demo reach event envelope	#14782 F3	Emits privacy-bounded `view` and meaningful `interaction` events with demo key, event kind, timestamp/window, and source category	Missing event stream => F3 remains blocked; no fake count	Source JSDoc / event contract note	Unit/probe showing events map to metric input
`METRIC` node write	#14442/#14446 + `ai/graph/businessSchema.mjs`	Deterministic metric identity; `claimClass`, `falsifyingQuery`, `windowSemantics`, `confoundDisclaimer`, `publicFlag`, `periodStart`, `periodClosed`, and finite `value` all present	Validation failure refuses the write and blocks launch evidence	Anchor & Echo JSDoc + release-gate note	Validator/probe evidence plus metric id
Developer-filter heuristic	ROADMAP "strangers counted" + #14790 Phase 0	Excludes developer/internal categories and records the heuristic in `falsifyingQuery` / `confoundDisclaimer` without public private identifiers	If the filter cannot be defended, metric is not publishable	Metric property text + release evidence line	Falsifying query reproduces included/excluded totals
Release / launch readback artifact	#14790 + release notes discipline	Public launch/release artifact cites metric id, window, value, provenance, and falsifying query	No artifact => no measured-reach claim	v13.2 release notes / launch issue comment	Greppable evidence line

Decision Record impact

Aligned-with #14442/#14446 and ADR-0024's business/time-series disposition. No ADR amendment is intended. If implementation needs a new claimClass, new business node property, or new durability rule, that is an ADR-0024 amendment and must not be smuggled into this leaf.

Acceptance Criteria

Each flagship demo covered by this release gate has a stable demo id / surface key before instrumentation begins.
View and meaningful-interaction events are mapped to the existing business metric schema without adding a new #14442 dashboard leaf.
Every produced METRIC node passes validateMetricProperties() and carries a non-empty falsifyingQuery, windowSemantics, confoundDisclaimer, strict boolean publicFlag, and deterministic identity fields.
Developer/internal traffic is excluded by a documented heuristic; the public artifact names the categories and query logic without exposing private identifiers.
The falsifying query can reproduce included count, excluded count, final published value, window, and demo key for each published reach number.
#14790 Phase 0 blocks announcement if the metric write, developer-filter evidence, or release/readback artifact is missing.
v13.2 release notes / launch artifact cite the measured value with metric id, window, provenance, and falsifying query; no raw likes/views or developer-circle counts are presented as traction.

Out of Scope

Implementing the demos themselves (#14789, #14646, #14781 journey leaves, and Fleet Manager / dock surfaces own that work).
Creating the #14442 CEO-dashboard slice, which remains gated on #14422 per ROADMAP.
Social-MCP posting, paid promotion, pricing, packaging, private targets, revenue strategy, or client-specific artifacts.
New analytics infrastructure beyond consuming the shipped business metric schema unless a later intake proves an explicit missing substrate.

Avoided Traps

Do not count raw page views, likes, maintainer retweets, or internal test traffic as stranger reach.
Do not announce a demo first and add measurement later; that violates #14790 Phase 0.
Do not publish private targets or private identifiers in public release artifacts.
Do not create a display-only dashboard to satisfy the word "dashboard" while #14422 still gates the real business slice.
Do not use this ticket to implement Fleet Manager or Qt-dock demo internals.

Parent / source measurement umbrella: #14782. Launch sequencing: #14790. Business metric source of authority: #14442 and #14446. Demo / journey surfaces: #14781, #14789, #14646, #14840. ROADMAP anchor: v13.2 traction guardrail.

Origin Session ID: 6ab85930-3c14-4b18-b3b3-97989d1e75c6

Retrieval Hint: "F3 demo reach metrics falsifiable stranger counts Ring-0 developer-filter falsifyingQuery METRIC #14782 #14790 #14442 #14446"

tobiu 3:43 PM

what the heck is this? not an actionable ticket for sure. closing as not planned.

tobiu closed this issue on 3:43 PM