[Performance/Acquisition] Establish reproducible capacity and latency envelope

[seonghobae]

Buyer-visible evidence gap — protected-main truth

Fresh protected main is exact 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c and remains protected. Repository correctness/security evidence is extensive, but protected main still has no first-party acquisition-facing capacity envelope that measures complete package-owned buyer paths. Existing focused performance questions, including #102's reconciliation candidate discovery, do not establish a repository-wide capacity contract.

The package already has bounded-resource and security controls. Active #319 additionally makes runtime admission materially more expensive and more realistic: before tenant binding/data SQL it traverses selectable/administerable role authority, callable SECURITY DEFINER authority, reachable ordinary-view authority, materialized-view definition provenance, directly/view-reachable foreign-data authority, and a cycle-safe pg_inherits foreign-ancestor closure that rejects ordinary or partitioned parents with foreign descendants. Benchmarking only the final tenant query would therefore omit part of the actual buyer path. This issue remains an evidence-readiness gap, not a claim that protected main is slow or unscalable.

Bounded acquisition target

Establish one reproducible benchmark/capacity program that distinguishes measured evidence from product guarantees and keeps provider variability outside local-engine claims unless separately measured.

For any applicable synchronous package-owned buyer path, the current commercial target is measured p95 <= 20 ms on a declared reference environment. Treat that as an acceptance target to validate, not a guaranteed SLO to publish before evidence exists. If the complete path exceeds it, profile the causal query/I/O/connection/runtime bottleneck and repair the hot path rather than shrinking the sample, omitting admission/security work, excluding slow phases, or manufacturing a warm-cache-only result.

Acceptance requires:

• define stable synthetic, non-sensitive workloads for package-owned preparation/tokenization, PostgreSQL persistence/lifecycle discovery, reconciliation/checkpoint application, bounded result streaming, and other commercially material local hot paths actually present on the then-protected tree;
• for lifecycle-outbox paths, measure the complete connection-acquisition -> live authority admission -> tenant binding -> data I/O -> cleanup lifecycle. Admission workloads must vary role/member cardinality, callable-definer cardinality/depth, ordinary-view graph cardinality/depth, reachable materialized-view definition-provenance cardinality/depth, directly/view-reachable foreign-relation count, and inheritance/partition depth × fanout including foreign descendants behind parent-only SELECT; do not benchmark only the terminal SELECT/INSERT;
• record exact source commit, package/lock identity, PostgreSQL major/image digest, schema/migration identity, Python version including 3.14, CPU architecture/count, memory limit, filesystem/storage class where material, database settings, worker/concurrency settings, row/cardinality distribution, payload-size distribution, warm/cold state, and benchmark tool identity for every published result;
• report p50/p95/p99 latency distributions, completed-work throughput, peak/steady memory, PostgreSQL connection/session pressure, query/lock behavior, and failure/saturation behavior where meaningful;
• separate local package/PostgreSQL time from provider HTTP queue/execution time; provider latency, quotas, pricing, and availability must not be folded into package throughput claims unless separately measured in a dated provider-backed test;
• exercise realistic tenant/cardinality growth, including [Operability] Restore automatic provider reconciliation through the validated Python boundary #102's candidate-discovery question, and capture EXPLAIN (ANALYZE, BUFFERS) or another reviewed planner/work measure before performance-only indexes/query complexity;
• profile catalog/admission queries separately when they dominate p95, including planner work, catalog I/O, recursive-CTE row growth, pg_inherits ancestry depth/fanout, foreign-source membership joins, connection setup, locks and CPU. Optimize causally while preserving fail-closed authority semantics; do not replace exact catalog evidence with mutable caches unless an independently invalidated/versioned authority design is reviewed first;
• prove bounded-resource behavior at and beyond the supported envelope: connection pool/worker pressure, lock contention, oversized batches/results, restart/reconciliation, backpressure, timeout/resource ceilings, and deterministic refusal must remain correct rather than merely fast;
• include repeatable soak/endurance evidence sufficient to expose connection/file-descriptor/memory growth and durable-state accumulation without promoting one successful run into an availability claim;
• define regression-comparison rules accounting for run-to-run variance and environment identity; any CI performance gate must use a reviewed defensible tolerance and fail closed on invalid/missing evidence rather than a brittle arbitrary wall-clock threshold;
• publish acquisition/operator capacity tables only for actually measured environments, with explicit non-guarantees and scaling assumptions; deployment-specific SLO/SLA, RPO/RTO, cloud sizing, provider quota and cost claims remain outside package authority unless separately evidenced;
• keep fixtures free of real prompts, credentials, DSNs, tenant/customer identifiers, provider resource IDs, or production content, and preserve bounded-observability rules in diagnostics/artifacts;
• preserve standalone + modular MSA operation, exact 100% owned-production statement/branch coverage, 100% public docstrings, supported Python including 3.14, PostgreSQL/container/package/security/SAST/SBOM/provenance/release evidence, and then-live exact-head/current-base governance; and
• route canonical PRD/TRD/architecture/operability/release documentation only through the then-authoritative canonical-documentation writer, separating IMPLEMENTED-ON-PROTECTED-MAIN, benchmark-only evidence, and deployment-specific claims.

Writer boundary — corrected 2026-09-07; do not infer a free lane

No benchmark source implementation is authorized merely because this issue exists. Current #319 is an active security/runtime writer and its exact admission implementation is candidate evidence until its protected stack is normally integrated. The benchmark lane must consume the then-current protected implementation or a deliberately stacked exact candidate without racing source ownership.

The earlier bounded-streaming adjudication remains: #58's retained branch and the historical reconciliation branch are superseded-retained evidence rather than present-tense writers. Likewise, historical canonical-documentation refs do not create a free documentation lane when an active documentation PR owns the same file. Before any benchmark implementation slice, freshly refetch protected main, every open PR/issue, non-default branches that touch intended paths, reviews/checks and live governance. Freeze overlapping paths rather than deleting, force-updating or destructively rebasing retained refs.

docs/product-technical-gap-baseline.md currently overlaps active documentation work, so performance evidence should be carried through the canonical documentation stack without replacing another writer's ledger wholesale.

Completion boundary

Close only after reproducible benchmark tooling and at least one protected-main-grounded reference capacity report are integrated and independently rerunnable from exact declared inputs, with results distinguishing local-engine evidence from external-provider/deployment claims. The report must state whether the applicable complete buyer path meets the p95 <= 20 ms target and, when it does not, preserve the measured profile and remediation boundary rather than suppressing the result. Benchmark success is not a certification, SLA, scalability guarantee, SOC 2/CSAP claim, or proof of production suitability by itself.

Refs #102, #198, #204, #229, #244, #316, #318, #319.

[seonghobae]

Fresh bounded inventory follow-up on protected main@b84f0c94154043a3473939c01bb6471de5a129ae:

• the complete branch-name inventory was re-enumerated across both pages (123 refs including main); no retained ref name contains benchmark;
• repository search still exposes no dedicated first-party benchmark/capacity harness or acquisition-facing capacity artifact on protected main; a broad search for throughput/capacity/latency/percentile/soak terminology returned no relevant benchmark authority;
• canonical documentation remains occupied by the active Draft/retained docs/canonical-documentation-* lineages; and
• numerous retained runtime/result/database branches remain, so branch-name absence is not changed-path proof that a new benchmark source lane is free.

Accordingly no benchmark branch was created in this pass. A future implementation slice must first compare every no-PR candidate head against the then-live protected main and prove the exact intended new/existing benchmark/test/workflow paths are non-overlapping. This preserves the issue as a measured-evidence target rather than manufacturing an unreviewed broad performance lane.

[seonghobae]

Fresh writer-boundary correction against protected main@b84f0c94154043a3473939c01bb6471de5a129ae:

The acquisition benchmark issue should not treat every retained branch name as one undifferentiated current runtime writer.

• agent/bounded-jsonl-result-streaming@64662a4410ff0ff83f150d72fee07b78c4e82d5b remains the exact retained head of closed-unmerged Draft feat(streaming): bound incremental result records #58 and is SUPERSEDED_RETAINED after the bounded-streaming slice was reconstructed and merged through feat(streaming): rebuild bounded result records on current main #172 on protected ancestry. Its historical broad diff is provenance, not a current benchmark/source lease.
• agent/bounded-jsonl-result-streaming-reconcile@5ec158ad7855a70ecebbc2ca886d81e3f1cdd3cc remains a distinct no-PR divergent ref and must be treated by exact path rather than branch name. Fresh exact evidence shows it overlaps database/durable lifecycle/schema/package/release/integration-test surfaces, so benchmark slices on those paths remain occupied; it does not prove ownership of unrelated tokenizer/orchestrator/provider-client paths merely because the branch name says result streaming.

Preserve both refs; do not delete, rename, rebase, force-update, or transfer historical checks/reviews.

Keep #307 status: blocked as a broad umbrella: a reproducible capacity program will span multiple currently owned source/test/workflow/docs surfaces, the repository retains 123 non-default refs, and Draft #229 separately occupies canonical documentation. Future benchmark work should therefore be decomposed into exact-path bounded slices only after an invocation-scoped writer inventory proves that slice exclusive. This comment narrows false historical writer attribution; it does not authorize a benchmark branch or capacity claim.

[seonghobae]

Fresh 2026-09-07 buyer-gap refresh. Protected main is now 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c. A repository-wide code search for literal p95 returns zero results, so the current buyer-path p95 ≤ 20 ms target is not an implemented/verified performance contract and must not be inferred from CI duration, unit tests, or the exact-head GREEN of #319.

For the next non-conflicting performance slice, treat 20 ms as an acceptance target only where the path is package-owned and latency-sensitive. Measure full connection/query/serialization lifecycle with realistic/right-cleared cardinality and payload distributions; do not shrink samples, exclude slow phases, or rely on unrealistic warm-cache setup. If p95 exceeds the target, retain the RED measurement and profile query plan/I/O/locking/connection/runtime costs before changing implementation. PostgreSQL paths should capture planner evidence such as EXPLAIN (ANALYZE, BUFFERS) where appropriate and verify connection cleanup plus saturation/failure behavior. Provider queue/execution time remains outside a local package latency claim.

No benchmark source/docs branch is started from this comment because current source/document writer overlap still has to be resolved path-by-path immediately before mutation. This issue remains the canonical buyer/performance acceptance path rather than creating a duplicate p95 issue.