[Hackathon] distributed-systems-architect: private_commerce — four-layer cross-plugin composition with joint validators

[Abi5678]

[Hackathon] distributed-systems-architect: private_commerce — four-layer cross-plugin composition with joint validators

Problem picked

None of the ten listed problems — this PR targets the gap they leave behind. Every merged hackathon plugin (gossip registry #24, streaming payments #21, hybrid_x25519 privacy #28, agent_receipts trust #26) was designed, tested, and validated in isolation. Nobody has asked what happens when they run together, and no validator in the repo can even express a cross-layer invariant. This PR is a scenario + validator submission per the charter ("a layer plugin or a scenario or a validator"): a private_commerce scenario that composes four merged plugins into one workflow, plus four joint validators that test emergent properties spanning layer boundaries.

What it does

Scenario (12 agents): 5 buyers discover sellers through per-agent gossip registries (partition-honest — buyers 0-1 are partitioned away for the first 3000 ticks and must wait for the heal), open per-tick streaming payments, and send bids wrapped in hybrid X25519 + ChaCha20-Poly1305 envelopes. 4 honest sellers decrypt, deliver, and issue Ed25519 cross-signed purchase receipts; they also settle among themselves in a directed receipt cycle, forming the strongly-connected honest anchor that collusion severance needs. The adversary — shill_seller-0 — looks legitimate on the registry, decrypts the bid, drains the stream, never delivers, and covers itself by wash-trading mutually co-signed fake receipts with shill-0. An auditor ingests receipts and negatives into the configured trust plugin and emits final scores.

Joint validators (registered as VALIDATORS["private_commerce"]):

Validator	Layers spanned	Invariant
commerce_discovery_precedes_bid	registry × privacy	every encrypted bid is preceded by an honest gossip discovery of that seller
commerce_bid_opacity	privacy × transport	the known bid plaintext never appears in any bid: wire message (send / receive / dropped)
commerce_undelivered_penalized	payments × trust	a seller that drained a stream without delivering ends below the trust threshold — despite wash-traded receipts
commerce_delivery_rewarded	payments × trust	every fulfilment is backed by a payment stream, and fulfilling sellers score above threshold

Adversarial discrimination (one YAML line each)

The charter asks for validators the reference plugin cannot satisfy. Here each cross-layer check is pinned to the specific plugin that makes it pass:

• privacy: hybrid_x25519 → noop: bid envelopes become plaintext; commerce_bid_opacity FAILS (the other three still pass — the failure is surgically attributable).
• trust: agent_receipts → score_average: the shill's wash-traded receipts raise its running average to 0.75; commerce_undelivered_penalized FAILS. Under agent_receipts the isolated mutual co-signing pair is severed by the SCC analysis and the shill collapses to 0.0 — the composition passes.

Both discriminations are integration tests (test_noop_privacy_fails_exactly_the_opacity_validator, test_score_average_trust_fails_exactly_the_penalty_validator) that assert the exact verdict vector, not just "something failed."

Design decisions & tradeoffs

• Ground-truth sidecar (bidmeta:): opacity is unfalsifiable unless the validator knows the plaintext. Buyers broadcast a bidmeta: marker declaring what they encrypted; the validator then proves that string never rides the wire in a bid: message. In production this sidecar would not exist; in a test rig, making the invariant checkable is the point.
• Marker broadcasts vs. functional sends: markers (discovered:, stream:*, fulfilled:, score:) are broadcasts — recorded in the trace at send time, so a dropped delivery can never make the trace lie about what an agent did. Functional messages (bid, ack, receipt) get 3× send redundancy with receiver-side dedup by ref/receipt-id; self-scheduled ticks get 5× redundancy (drop-chain death probability ≈ 0.05⁵). This is the same pattern the gossip scenario ([Hackathon] bori7-onchain-registry-author: gossip registry plugin with partition-honest eventual consistency #24) uses, extended to point-to-point traffic.
• Deterministic pairing: buyer i targets the i-th sorted discovered seller, so with 5 buyers and 5 sell-capable cards, the shill gets exactly one victim under every seed — the adversary is guaranteed to fire, and the penalty validator fails loudly if it ever doesn't ("the adversary never fired"), rather than passing vacuously.
• Trust threshold 0.3: an honest seller with one corroborated purchase receipt scores 1 − exp(−5/10) ≈ 0.39 under agent_receipts; a severed shill scores exactly 0.0; the reference neutral prior is 0.5. 0.3 separates every honest outcome from the severed adversary with margin on both sides, and sits below the 0.5 prior so score_average's wash-trade inflation (0.75) is caught.
• Per-agent plugin wiring uses the runner's existing _agent_plugins override channel (same as [Hackathon] bori7-onchain-registry-author: gossip registry plugin with partition-honest eventual consistency #24): per-agent gossip views, per-buyer streaming ledgers, per-agent X25519 keypairs cross-registered at build time. No runner changes needed.

Test rigor

25 tests in packages/nest-plugins-reference/tests/test_private_commerce.py:

• 17 unit tests covering pass / fail / absent-marker / vacuous-pass paths for all four validators (e.g. zero-total stream is not a drain; a delivered stream is not an offense; unpaid fulfilment is caught).
• 2 Hypothesis property tests: arbitrary junk markers interleaved with valid ones never crash any validator; N-fold marker duplication (the drop-redundancy scenario) never changes any verdict.
• 6 integration tests booting the full simulator: all validators green under seeds 42 and 7; byte-identical traces under a repeated seed; different traces under different seeds; and the two exact-verdict adversarial discriminations above.

How to verify

uv run nest run scenarios/private_commerce.yaml
uv run python -c "
from pathlib import Path
from nest_core.validators import validate_trace
for r in validate_trace(Path('traces/private_commerce.jsonl'), 'private_commerce'):
    print('PASS' if r.passed else 'FAIL', r.name, '-', r.detail)
"
# Adversarial: edit scenarios/private_commerce.yaml, set privacy: noop → opacity FAILS
# Adversarial: set trust: score_average → undelivered-penalty FAILS
uv run pytest packages/nest-plugins-reference/tests/test_private_commerce.py -v

Full CI (uv sync && uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest -v) is green locally: 761 passed, 0 ruff, 0 pyright.

Persona

distributed-systems-architect: the submission's whole thesis is that correctness of parts does not compose for free. The code reflects it — redundancy budgets computed from the drop rate, partition-aware pairing deadlines, an SCC-severance-aware threshold derivation, and validators that treat the trace as the only source of truth (markers recorded at send time so drops can't hide behavior). The novelty is not any one algorithm; it is the instrumented composition and the two one-line adversarial swaps that attribute each cross-layer failure to the exact layer that caused it.

[Copilot]

Pull request overview

This PR adds a new Tier-1 “private_commerce” scenario that composes four previously-merged layer plugins (gossip registry, streaming payments, hybrid X25519 privacy, and receipt-based trust) and introduces joint validators that check cross-layer invariants over the resulting trace.

Changes:

• Added private_commerce scenario YAML and a built-in scenario factory that wires per-agent plugin overrides (gossip registries, hybrid privacy keypairs, streaming payments ledgers).
• Added four “private_commerce” joint validators to nest_core.validators and registered them under VALIDATORS["private_commerce"].
• Added comprehensive unit/property/integration tests for the scenario + exact adversarial discriminations, and updated validator registry tests to include the new scenario type.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scenarios/private_commerce.yaml	New scenario wiring for the four-layer composition, failures (drop + partition heal), and trace output.
packages/nest-plugins-reference/tests/test_private_commerce.py	Unit/property/integration coverage for the new joint validators and end-to-end scenario runs.
packages/nest-core/tests/test_validators.py	Updates expected validator registry keys to include private_commerce.
packages/nest-core/nest_core/validators.py	Implements and registers four new cross-layer “private_commerce” validators.
packages/nest-core/nest_core/scenarios.py	Registers the new built-in scenario loader branch for private_commerce.
packages/nest-core/nest_core/scenarios_builtin/private_commerce.py	Implements the 12-agent scenario and per-agent plugin override wiring.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.