feat: initial proxy outcome attribution library

[pnlabs-dev]

Summary

Introduces the first public PN Labs implementation of proxy-outcome: a deterministic, zero-runtime-dependency library that classifies HTTP/proxy observations without inventing root cause or endpoint-health evidence.

Core model

The public API separates:

1. observed outcome — what the supplied status/error supports;
2. root-cause attribution — only when evidence supports it;
3. proxy-layer evidence — whether the proxy path/auth layer is implicated;
4. proxy endpoint-health evidence — a stronger, separate claim;
5. automatic rotation evidence — only emitted when v0.1 has sufficiently strong endpoint evidence.

Key invariants:

• HTTP 403 / 429 / 451 / 5xx do not identify root cause from status alone;
• 451 is a legal-restriction observation, not an automatic geo claim;
• 3xx is a redirect outcome, not automatically a usable success;
• ERR_PROXY_CONNECTION_FAILED is a proxy-path failure, not automatic proof that the endpoint is unhealthy;
• HTTP 407 / explicit proxy-auth signals identify the proxy-auth layer but do not automatically justify endpoint rotation;
• automatic endpoint-health/rotation evidence requires an explicit independent failed endpoint probe supplied by the caller.

Included

• deterministic Python classifier;
• typed outcome/evidence model;
• JSON CLI;
• conservative ambiguous fallback;
• taxonomy + architecture documentation;
• security policy + public/private boundary documentation;
• design-partner issue template with data-minimization guidance;
• MIT license;
• CI across Python 3.10 / 3.11 / 3.12.

Security / public-repository hardening

This repository is intentionally limited to the transparent deterministic baseline.

• no runtime network I/O or telemetry;
• no credential storage;
• raw header values are not inspected by the classifier;
• raw header/body/error values are not intentionally emitted in classifier evidence;
• malformed CLI header input is not echoed into error output;
• .gitignore blocks common secret/capture artifacts;
• public issue/design-partner docs prohibit credentials, cookies, private URLs/IPs, internal hostnames, raw production logs/HAR/PCAP, customer/personal data, and private infrastructure details;
• CI uses a non-echoing, vendor-neutral repository hygiene gate for common secret/token shapes, credential-bearing URLs, private IPv4 literals, sensitive filenames, and email addresses;
• CI permissions are read-only for repository contents, checkout credentials are not persisted, and external actions are pinned to full release commit SHAs.

Commercial control-plane implementation, private routing/scoring logic, provider-private configuration, private infrastructure details, and non-public datasets remain outside this repository.

Clean history

The feature branch was rebuilt from the final reviewed tree and force-updated to a single commit directly on top of main.

• base: ab05187357a4dc4fa7079217e8f881a216c52067
• head: ad43d432f6ce5d319510f227c1f1aff0eb79e100
• PR commits: 1
• changed files: 19

Final validation

Validation on the clean-history head ad43d432f6ce5d319510f227c1f1aff0eb79e100:

• Python 3.10: PASS
• Python 3.11: PASS
• Python 3.12: PASS
• public repository hygiene gate: PASS
• package build/install from source: PASS
• compile check: PASS
• unit tests: 17/17 PASS
• installed CLI smoke tests: PASS

CI run: 32397259192.

Merge posture

The semantic, packaging, CI, public-security, IP-boundary, and branch-history review items are resolved. No merge has been performed by this preparation step.

[pnlabs-dev]

PN Labs review — CHANGES NEEDED before merge

CI is green, but I would keep this PR in draft until the attribution semantics are hardened. The repo's core promise is evidence-before-action, so false attribution here would undermine the exact thesis we want PN Labs to demonstrate.

Blocking — P0/P1

1. HTTP status is being used to infer the actor too aggressively.
   403, 429, 451, and 5xx are currently mapped directly to Attribution.TARGET/UPSTREAM with high confidence. A status alone does not prove which hop emitted it; CDN/WAF/gateway/proxy-provider/intermediary responses can produce the same codes. Keep observed outcome orthogonal from root-cause attribution. Without emitter evidence, attribution should remain ambiguous/unknown rather than target-specific.

2. Generic proxy-connect errors are too strong as bad-proxy + auto-rotation evidence.
   ERR_PROXY_CONNECTION_FAILED can be caused by client/protocol incompatibility, browser proxy support, local/network policy, configuration, or endpoint failure. The current bad_proxy_evidence=True + automatic_rotation_evidence=True can poison a healthy endpoint. Prefer a PROXY_PATH_FAILURE/transport outcome with no automatic demotion until a control probe or repeated endpoint-scoped evidence confirms it.

3. All 3xx responses are classified as SUCCESS with confidence 1.0.
   In scraping, redirects to login, consent, challenge, CAPTCHA, or an error route are common. A 302/307 is not automatically a usable success. Add a separate redirect outcome or require final-response context before calling success.

4. HTTP 451 is named TARGET_GEO_RESTRICTION, which is too narrow.
   451 means unavailable for legal reasons; geography may be involved, but is not guaranteed. A neutral name such as HTTP_LEGAL_RESTRICTION / ACCESS_RESTRICTION would preserve evidence without inventing cause.

CI hardening — P1

5. Current tests bypass packaging.
   tests/test_classifier.py manually inserts src into sys.path, so CI can stay green even if pip install . or the console entry point is broken. Before first public merge, CI should install/build the package and smoke-test both proxy-outcome classify ... and python -m proxy_outcome ....

Non-blocking

• Actions currently emit Node-runtime deprecation warnings; update/pin the actions when convenient.
• SECURITY.md refers to a private/public contact channel on the PN Labs profile; make sure that channel actually exists before relying on it.

What is already good

• 407 auth failure is correctly separated from automatic rotation.
• 403/429/451 do not automatically count as bad-proxy evidence.
• Ambiguous timeout fails closed.
• Zero runtime dependencies and machine-readable output are good choices.
• Design-partner benchmark framing is strong and avoids bypass positioning.

Recommendation: keep PR #1 draft, patch the semantic model first, extend CI to test installation/CLI, then rerun review + CI before merge.

[pnlabs-dev]

PN Labs follow-up review — initial blockers addressed

Second-pass review completed on head 2ace067a2b01e5c84757ecde06d3d2a55a1a2e74.

The initial blockers are resolved:

• HTTP response outcomes no longer invent target/upstream root cause from status alone;
• proxy-path failures are separated from endpoint-health evidence and automatic rotation;
• 3xx is a distinct redirect outcome rather than automatic usable success;
• HTTP 451 is represented as a legal-restriction observation rather than a geo claim;
• packaging is exercised by CI before tests;
• installed CLI entry points are smoke-tested;
• raw header values are not inspected by the classifier;
• CLI error handling avoids echoing malformed sensitive input;
• public security/data-minimization documentation and an explicit OSS/private boundary are present;
• repository hygiene gate passes without echoing matched values;
• workflow token permissions are read-only, checkout credentials are not persisted, and Actions are pinned to full release commit SHAs.

Final CI run 32394871111: Python 3.10 / 3.11 / 3.12 all PASS; package build/install, compile, 17 tests, CLI smoke tests, and public-repository hygiene check all PASS.

No remaining source-level merge blocker found in the reviewed scope. Keep the PR draft until explicit merge authorization.

[pnlabs-dev]

Final merge-prep review

Clean-history preparation is complete.

• feature branch reduced to one commit directly on top of main;
• final tree preserved exactly across the squash;
• current head: ad43d432f6ce5d319510f227c1f1aff0eb79e100;
• CI run 32397259192: PASS;
• Python 3.10 / 3.11 / 3.12: PASS;
• public repository hygiene gate: PASS;
• source install/build + compile: PASS;
• unit tests: 17/17 PASS;
• installed CLI smoke tests: PASS;
• current public tree uses vendor-neutral hygiene labels and contains only the intended OSS baseline.

No source-level or CI-level merge blocker remains from this review. Merge is intentionally left as a separate authorized action.