Imported from YaroTanko/streamlens-performance-challenge (
AGENTS.md). Install upstream withnpx skills add YaroTanko/streamlens-performance-challenge. Copyright stays with the author.
Instructions for AI Coding Agents
This repository is a timed Go performance assessment. Help the candidate analyze and improve the existing implementation while preserving the contract. AI use is explicitly allowed; do not conceal uncertainty or claim benchmark gains that were not measured.
Authority and scope
PRD.mdis the product and assessment source of truth.TASK.mddefines the candidate-editable scope and scoring policy.DESIGN.mdsummarizes architecture and invariants.
Assessment version 3 is active and anchored by the immutable baseline-v3
package and workflow pin. Older recorded submissions retain their original
assessment-version contract.
For a candidate pull request, edit exactly:
internal/analyzer/engine.goOPTIMIZATION.md
Do not edit or generate tests, fixtures, benchmark code, scripts, module metadata, other documentation, workflows, or additional implementation files. If a requested change requires a protected path, explain the conflict instead of making the edit.
Version 3 candidate source policy
For baseline-v3, keep candidate engine.go within the documented
safe-standard-library subset. Do not import C, os, os/exec, unsafe,
syscall, testing, flag, log, log/slog, log/syslog, runtime/debug,
runtime/pprof, or runtime/trace. Do not use package-level runtime functions
or variables, print/println, fmt.Print*, unsafe cgo/compiler directives, or
source markers intended to recognize the protected benchmark.
These restrictions apply only to the submitted internal/analyzer/engine.go.
Profiling and analysis tools outside that file remain unrestricted: help the
candidate use pprof, system profilers, debuggers, shell tools, and AI assistance
as appropriate. Do not move profiling or process-control behavior into the
analyzer to evade the boundary.
The version 3 guard parses and type-checks exact committed source, but it is a workflow aid rather than a complete security boundary. Keep every optimization ordinary, small, and human-reviewable within the 30-minute task; never imply that passing the source audit proves benign behavior.
At version 3 activation, assessment construction starts from the immutable
baseline and overlays exactly internal/analyzer/engine.go and
OPTIMIZATION.md. Candidate tests, scripts, module metadata, generated files,
submodules, and workflows are not copied or executed. Fixed trusted commands run
in a restricted digest-pinned container with bounded deadline and output, and the
trusted parent performs validated CID cleanup and writes evidence manifests. A
real canary using that exact image is required before activation; fake-runtime
tests do not satisfy that requirement.
Working rules
- Inspect and profile the implementation before selecting an optimization. The
repository provides
make profile-cpuandmake profile-alloc, but another profiler is equally acceptable. - Preserve the specified parsing, validation, filtering, aggregation, ordering, error, and cancellation behavior.
- Do not convert ignored fields, interpret only the last exact duplicate field, and preserve earliest-line error precedence.
- Preserve input-order
float64sum semantics and overflow errors; do not reorder additions or substitute approximate arithmetic. - Use only the Go standard library and preserve the exported in-repository API and JSON format.
- For an active version 3 assessment, also preserve the safe-standard-library subset above; do not propose a prohibited package or sensitive runtime/process/output API as an optimization.
- Never weaken, bypass, special-case, or detect tests and benchmark workloads.
- Never replace specified results with approximations or skip valid input work.
- Keep the change reviewable within a 30-minute exercise.
- Record the measured or expected effect and any trade-off in
OPTIMIZATION.md. - Include a non-empty
Profile evidence:bullet naming the command or tool and an observed hotspot. Do not claim profile evidence that was not observed.
Verification
Run:
make check
make benchmark
# Run at least one profiling target (or use another profiler):
make profile-cpu # CPU hotspots
make profile-alloc # allocation hotspots
If make is unavailable, run:
go vet ./...
go test ./...
go build ./...
GOMAXPROCS=1 go test -run '^$' -bench . -benchmem -cpu=1 ./internal/assessment
Treat local benchmark changes as directional because CI performs the authoritative
same-run baseline comparison. Before finishing, inspect the diff and confirm that
only the two allowed files changed and that OPTIMIZATION.md contains 5–10 concise
bullets explaining the profile evidence, approach, expected effect, trade-offs,
and verification. Profiling is diagnostic and remains separate from scoring.
