Response System

The response system allows users and agents to capture structured feedback, assessments, and data points against entities.

Scoped Criteria Sets (Edge Scoring)

Amble supports Scoped Criteria Sets, which allow you to score or evaluate relationships (edges) connected to an entity, rather than just the entity itself. This is often referred to as "Edge Scoring."

Concept

By default, a criteria set has an entity scope ({ type: "entity" }), meaning the dimensions apply directly to the primary record. With a relation scope ({ type: "relation", fieldKey: "target_markets" }), the evaluation is distributed across the entities connected to the primary record via the specified fieldKey.

When a scoped criteria set is submitted:

1. The values payload is a nested matrix keyed by the connected entity ID: { [connectionId: string]: { [dimensionKey: string]: value } }.
2. The system resolves all target entities and validates that the dimensions match the criteria set.
3. Scores are computed as the mean across all evaluated edges. A 100 on one connection and a 50 on another results in an overall normalized score of 75.

UI Integration

• EdgeMatrixForm: Scoped criteria sets are rendered using a matrix interface where each row represents a connected entity.
• MatrixAggregationView: Relation-scoped responses aggregate into a per-connection matrix view — a BubbleChart plots each connection on two numeric dimensions (X/Y with optional Z bubble size), backed by a sortable leaderboard that shows each connection's aggregate per dimension plus a weighted score. Users pick the aggregation strategy (mean / median / min / max), toggle a respondent-dot overlay, and everything persists in the URL so chart views are shareable.
• Compare Views: Still a fallback for now — captured as a follow-up.
• Promotions: Scoped responses cannot be directly promoted to the primary entity, as they represent data about the relationships, not scalar fields on the entity itself.

Matrix aggregation internals

• computeResponseAggregate() in features/responses/lib/aggregate-matrix.ts is the pure aggregation function. It walks each response's per-connection value map, collects numeric values per dimension, applies the strategy, and computes a weighted/normalized score per connection using the criteria set's weights and scales. Both the server's aggregateResponses() and the client's MatrixAggregationView call this fn so strategy switches update without a server round-trip.
• ResponseAggregation.byConnection is an additive field on the server's aggregate payload. Entity-scope responses leave it undefined; relation-scope responses populate it.
• The BubbleChart component was extended with an optional overlayData prop — a second <Scatter> layer rendered underneath the primary dots at reduced opacity for the respondent overlay.

URL state keys for MatrixAggregationView

x=<dim> y=<dim> z=<dim> agg=mean|median|min|max overlay=1 sort=<dim|score|title> dir=asc|desc — all optional; defaults are the first two numeric dimensions, mean aggregation, overlay off, and score-desc leaderboard sort.

Claim aggregates (source-item → claim rollup)

For graphs where source-items evidence claims (DOC'S and any tenant that reuses the pattern), promoted evidence-quality responses roll up onto every supporting claim as two denormalized keys on entities.content:

• source_count — number of unique source-items supporting the claim
• source_quality_avg — mean of per-source-item dimension means

Data flow

1. A user or agent promotes a source-item's evidence-quality response → Supabase emits response.promoted.
2. recomputeClaimAggregatesOnResponse (Inngest listener) slug-gates on the source-item entity type + evidence-quality criteria set.
3. step.run("list-supported-claims", getSupportedClaimIds) resolves the claim set for that source-item.
4. step.run("fanout", () => inngest.send([...])) emits one claim.aggregate.recompute event per claim.
5. recomputeClaimAggregateForClaim consumes each event with per-claim concurrency limit 1. It calls recomputeSingleClaimAggregate, which re-derives source_count / source_quality_avg and writes via the public.apply_claim_aggregate RPC.

Concurrency contract

recomputeClaimAggregateForClaim declares:

concurrency: [
  { limit: 10 },
  { limit: 1, key: "event.data.tenant_id + ':' + event.data.claim_id" },
]

The per-claim limit-1 tier is the correctness contract — two source-items that land on the same claim inside the same Inngest window are serialized end-to-end (read → derive → write), which prevents the stale-aggregate race that burst traffic previously surfaced. The global cap protects Postgres from unbounded write pressure. Inngest SDK 3.x caps the tuple at 2, so a per-tenant fairness tier is tracked as a follow-up.

Atomic write invariant

public.apply_claim_aggregate(p_tenant_id, p_claim_id, p_source_count, p_quality_avg) performs a single row-locked UPDATE entities SET content = content || jsonb_build_object('source_count', ..., 'source_quality_avg', ...). This eliminates the cross-key clobber that the previous TypeScript read-merge-write suffered — any other writer touching content between the SELECT and UPDATE is no longer silently overwritten. The function is SECURITY DEFINER with empty search_path; EXECUTE is revoked from authenticated + anon and granted only to service_role, so direct PostgREST invocation from a user session is impossible. A 0-row result (deleted claim or cross-tenant id) is a graceful no-op — recomputeSingleClaimAggregate returns { updated: false } without throwing and Inngest does not retry.

PR #842 dedupe invariant

recomputeSingleClaimAggregate preserves the newestByEntity Map dedupe pattern from PR #842: when a source-item has multiple promoted responses for the same criteria set (re-promotion after reviewer correction), the newest row wins. Counting every promoted row would double-count that source-item in the claim average. Covered by a dedicated test case in recompute-single-claim-aggregate.test.ts.

Generic across tenants

The listener keys on tenant-configurable slugs via getSourceItemEntityTypeSlug() and getEvidenceQualityCriteriaSlug() (honoring SOURCE_CHILD_TYPE_SLUG / EVIDENCE_QUALITY_CRITERIA_SLUG env overrides). Tenants that use different slugs for the same pattern can set those envs; tenants that use a fundamentally different graph shape can wire their own listener and call recomputeSingleClaimAggregate / apply_claim_aggregate directly.