From 93110beedb79a81023ad1903761471223f384dd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=B5=9C=EC=98=81=EA=B8=B0?= <dch0202@rsquare.co.kr>
Date: Thu, 30 Jul 2026 11:47:52 +0900
Subject: [PATCH 1/3] knowledge: ingest 5 verified insight(s) into 2 pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

testing/docs-as-spec/document-conformance-checks (new category): positive +
negative control per check for gates whose subject is a document; validate the
pattern on a conforming sibling when the target file does not exist yet; split
the requirement into structure / normative modality / enum completeness /
cross-reference axes, each with a mutation that breaks only what it owns; pair
coverage with value-validity; split Markdown rows on unescaped pipes.

backend/common/storage/object-key-persistence (new category): persist the upload
response Key (+Bucket) and derive URLs on read — Location is produced by two
different code paths split at the managed uploader part size.
---
 .dev-loop/INGEST_REPORT.md                    | 189 ++++++++++++++++--
 INDEX.md                                      |   4 +-
 log.md                                        |   2 +
 .../common/storage/object-key-persistence.md  |  75 +++++++
 wiki/backend/index.md                         |   8 +-
 .../document-conformance-checks.md            |  88 ++++++++
 wiki/testing/index.md                         |  12 +-
 7 files changed, 350 insertions(+), 28 deletions(-)
 create mode 100644 wiki/backend/common/storage/object-key-persistence.md
 create mode 100644 wiki/testing/docs-as-spec/document-conformance-checks.md

diff --git a/.dev-loop/INGEST_REPORT.md b/.dev-loop/INGEST_REPORT.md
index 2ff3871..bf984cb 100644
--- a/.dev-loop/INGEST_REPORT.md
+++ b/.dev-loop/INGEST_REPORT.md
@@ -1,35 +1,180 @@
-# Knowledge flush — 1 insight
+# Knowledge flush — 5 insight(s) → 2 pages
 
-Source: RNR-3440 (사내 잠재매물 주간 추출 스크립트 메모리 피크 저감). Candidate:
-"QueryPie 프록시 경유로 대용량 결과를 스트리밍할 때 server-side named cursor 대신
-일반 커서 + `fetchmany` + openpyxl `write_only`."
+Queue drained: 5 pending candidates across 3 sessions. Four of them describe the
+same situation at different granularity and were folded into one page (AGENTS.md
+"one case per page" cuts by _situation_, not by candidate); the fifth is
+unrelated and got its own page.
+
+| #   | Candidate (hash)   | Claim                                                                                                                                                | Outcome                                                                  |
+| --- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 1   | `f997639131d8ec9e` | Validate a grep gate on a conforming sibling file before adopting it                                                                                 | Folded → `testing-docs-as-spec-document-conformance-checks` (Do this §2) |
+| 2   | `739b75ed972c6078` | Token-presence gates are blind three ways; split into structure / modality / row-completeness / cross-reference axes with per-axis negative controls | Folded → same page (Do this §3)                                          |
+| 3   | `2e3fcd105c8512fa` | Persist `s3.upload()` `Key`, not `Location`                                                                                                          | New page `backend-common-storage-object-key-persistence`                 |
+| 4   | `39dfae0d5a813cb4` | Pair a coverage check with a value-validity check, each with its own negative control                                                                | Folded → same page (Do this §4)                                          |
+| 5   | `18dc623000d54f07` | Split Markdown rows on unescaped pipes only                                                                                                          | Folded → same page (Edge cases + Instead of)                             |
 
 ## Verified best-practice
 
-**Claim 1 — psycopg2 server-side (named) cursor requires a transaction; fails under autocommit.**
-- Source: psycopg2 usage docs — `https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst` (via Context7). Quote: "Named cursors are typically created 'WITHOUT HOLD', meaning they exist only within the current transaction. Attempting to fetch from them after a commit or in autocommit mode raises an exception."
-- Matches my live repro (`can't use a named cursor outside of transactions`). → **verified**
+### Insights 1, 2, 4 — controls on a document-conformance check → `confidence: verified`
+
+**Claim.** A checker is unproven until it has been run against both a conforming
+input (must PASS) and a deliberately-broken input (must FAIL), one control per
+check; presence checks do not establish correctness.
+
+Sources checked:
+
+- **ESLint `RuleTester`** — https://eslint.org/docs/latest/integrate/nodejs-api#ruletester —
+  fetched; requires both a `valid` array (rule must not fire on compliant code)
+  and an `invalid` array whose cases must assert the errors the rule produces.
+  This is the positive/negative control pair as an enforced API shape.
+- **Semgrep rule tests** — https://docs.semgrep.dev/writing-rules/testing-rules —
+  fetched; `ruleid:` annotates true positives and `ok:` true negatives, both in
+  the same test file. Second independent tool converging on the same requirement.
+- **Google Testing Blog, mutation testing** — https://testing.googleblog.com/2021/04/mutation-testing.html —
+  already cited elsewhere in this wiki; supports "insert a fault, require the
+  check to fail" as the measure of detection.
+- **JSON Schema `required`** — https://json-schema.org/understanding-json-schema/reference/object —
+  fetched; `required` asserts key presence and constrains no value (a required
+  property may even be `null`). This is the canonical statement of the
+  coverage-vs-validity split that insight 4 hit empirically.
 
-**Claim 2 — a client-side (default) cursor pulls the whole result set to the client on execute; `fetchmany` only caps the Python-list explosion.**
-- Source: psycopg2 cursor/usage docs + FAQ (named-cursor advantage = "data is fetched in chunks … minimal client memory"). By contrast the default cursor buffers the full result in libpq. → **verified**
+**How verified.** The two linter sources are official docs for tools whose entire
+job is "run a rule against a document/AST", and both mandate the two-sided test.
+The candidates' own evidence (an independent auditor's 8 mutations passing a
+16-gate suite; a `Bogus` cell surviving a coverage check) is the field half.
+Insight 1's specific mechanism — a missing target file makes _every_ pattern
+red, so red carries no information about the pattern — is a direct logical
+consequence, and the candidate reports the positive control actually run
+(7 sections matched on the conforming sibling `rfcs/0005`).
 
-**Claim 3 — openpyxl `write_only` gives near-constant memory (<10 MB); one save only; lxml is for serialization speed, not the memory saving.**
-- Source: openpyxl Optimised Modes — `https://openpyxl.readthedocs.io/en/stable/optimized.html` (via WebSearch). "keeping memory usage under 10Mb"; "A write-only workbook can only be saved once"; "make sure you have lxml installed" for large dumps (speed).
-- This **corrects** the raw candidate's "lxml unnecessary" → precise form: unnecessary *for the memory win*, recommended *for large-dump speed*. Confirmed by my server test (write-only worked with lxml absent). → **verified**
+### Insight 5 — unescaped-pipe splitting of GFM table rows → `confidence: verified`
 
-**Claim 4 — QueryPie blocks `BEGIN`, so server-side cursor is impossible there.**
-- Environment-specific, no external source. Live repro in gui context: `autocommit=False` + named cursor → `[ENGINE] No permission to execute BEGIN statement`. → **field-tested**. Generalized in the page to "a read-only access-control proxy that blocks transaction control", with QueryPie as the concrete example (not a product-specific page).
-- Memory figure 838 MB → 38 MB (300k synthetic rows) is my RNR-3440 measurement (`ru_maxrss`, separate processes).
+- **GFM spec, tables extension** — https://github.github.com/gfm/#tables-extension- —
+  fetched. Cells are "separated by pipes (`|`)", and Example 200 shows you
+  "include a pipe in a cell's content by escaping it, **including inside other
+  inline spans**" (`f\|oo`, and an escaped pipe inside a code span and inside
+  emphasis). So `\|` is legal cell content and `split("|")` overcounts a correct
+  row.
+- **Reproduced here.** Ran the candidate's `re.split(r"(?<!\\)\|", row)` over both
+  new pages: cell counts come out uniform per table (4/4/4/4, then 3×6, 2×8,
+  3×7). The two rows in this PR that carry an escaped pipe in their text are
+  exactly the rows a naive split would have mis-flagged — the rule's own page is
+  its positive control.
+
+### Insight 3 — persist `Key`, not `Location` → `confidence: verified`
+
+- **S3 `CompleteMultipartUpload` API reference** — https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html —
+  fetched. `Key` is documented as "The object key of the newly created object";
+  `Location` is documented only as "The URI that identifies the newly created
+  object", with **no encoding guarantee**. That asymmetry is the load-bearing
+  fact: only one of the two fields has a contract.
+- **`AWS.S3.ManagedUpload` docs** — https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3/ManagedUpload.html —
+  fetched. Callback data carries `Location`, `ETag`, `Bucket`, `Key`;
+  `minPartSize = 1024 * 1024 * 5` and default `partSize` is 5 MB. Confirms the
+  candidate's 5,242,880-byte boundary and that `Key` is present on both paths.
+- **`lib/s3/managed_upload.js` source** — https://github.com/aws/aws-sdk-js/blob/master/lib/s3/managed_upload.js —
+  fetched from `raw.githubusercontent.com`. `finishSinglePart` builds
+  `data.Location` from `endpoint.protocol + '//' + endpoint.host + httpReq.path`
+  and sets `data.Key` from `params.Key`; `finishMultiPart` takes the service's
+  `Location` and applies only `.replace(/%2F/g, '/')`. Exactly the two producers
+  the candidate described, verified line-for-line against current master.
+- **aws-sdk-js issue #1158** — https://github.com/aws/aws-sdk-js/issues/1158 —
+  fetched. Reported side by side: multipart returns
+  `…/stream-uploads%2Fkokoko.gif`, single-part returns `…/stream-uploads/kokoko.gif`,
+  and `Key` is identical in both. Independent confirmation that `Location` is
+  path-dependent and `Key` is stable.
+- **aws-sdk-js-v3 issue #5656** — https://github.com/aws/aws-sdk-js-v3/issues/5656 —
+  fetched. Same structural split in v3 `lib-storage`: `__uploadUsingPut`
+  constructs `Location` client-side, `CompleteMultipartUploadCommand` does not.
+  Widened `applies_to` to `[aws-s3, aws-sdk-js-v2, aws-sdk-js-v3]`. (Closed for
+  staleness — no maintainer fix, so the directive is the workaround, not a bug
+  that has since been patched.)
+
+**One scope correction against the candidate.** The candidate asserted the
+multipart form is specifically `space → +`. What is _documented/reproduced_ in
+public sources is the slash case (`/` → `%2F`, visible in #1158 and implied by
+the SDK's `%2F`-only repair). The `+`-for-space observation is field evidence
+from the originating production incident, consistent with form-urlencoding but
+not shown in a cited source. The page therefore labels the encoding column
+"Observed form" and does not claim a documented `+` contract; the **directive**
+(store `Key`) is fully verified and does not depend on which character it is.
 
 ## Existing-layer check
 
-- Pages read: `databases/index.md`, `databases/query-optimization/keyset-pagination.md`, `backend/python/index.md`.
-- Overlap: keyset-pagination is the nearest neighbor (both handle large result sets) but a **distinct** topic — pagination splits the read into many bounded queries; this page streams a *single* query's result in chunks. Not a duplicate → new page + **bidirectional `related` link** added to both.
-- backend/python has no DB-cursor page; the psycopg2/openpyxl specifics live as concrete examples inside the databases page rather than a separate python page (no duplication).
-- Conflicts: none found.
+Pages read before routing:
+
+| Read                                                                                                    | Why                                              | Result                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INDEX.md`                                                                                              | Domain routing                                   | testing vs qa vs backend decided below                                                                                                                                                                                                                                                                                    |
+| `wiki/testing/index.md` (all 8 "load when" lines)                                                       | Overlap scan                                     | No page covers document/spec checking                                                                                                                                                                                                                                                                                     |
+| `wiki/testing/quality/tests-that-cannot-fail.md` (full)                                                 | Nearest neighbour — owns "prove a test can fail" | **Overlap, not duplication.** It owns mutation-and-require-red for _test code_ (its never-fails table is Jest/mock/async-shaped). It has no positive-control half and nothing about documents. Kept separate; the new page `related:`-links it and routes to it from an edge-case row ("subject is code, not a document") |
+| `wiki/testing/quality/minimum-case-set.md`, `behavior-not-implementation.md`                            | Overlap scan                                     | Case selection / assertion targets for code; no conflict. `minimum-case-set` added to `related:`                                                                                                                                                                                                                          |
+| `wiki/qa/index.md` + `process/release-gates.md`, `acceptance-criteria.md`                               | Insights 2 and 5 were tagged `domain: qa`        | `release-gates` is about _which_ gates a release must clear, not whether a gate can fail — no overlap. `acceptance-criteria` owns "make the requirement testable", which is upstream of "check the document encodes it"; linked in `related:` and in an edge-case row so the two compose                                  |
+| `grep -ril` over `wiki/` for mutation / markdown / negative control / linter / lint rule / docs-as-spec | Whole-wiki dedup                                 | Only `tests-that-cannot-fail` hit meaningfully; the rest are incidental word matches in frontend/security/backend pages                                                                                                                                                                                                   |
+| `wiki/backend/index.md` + all 8 `common/` categories                                                    | Insight 3 routing                                | No storage/object-storage page exists                                                                                                                                                                                                                                                                                     |
+| `grep -ril` over `wiki/` for s3 / multipart / object storage / presigned / url-encod                    | Whole-wiki dedup for insight 3                   | Zero real hits (`column-data-types.md` and `severity-and-priority.md` match on unrelated substrings)                                                                                                                                                                                                                      |
+
+**Conflicts flagged:** none. No existing directive is contradicted or overwritten;
+both pages are additive.
+
+**Merge-before-create decision.** Insights 1/2/4/5 merged into a single _new_
+page rather than appended to `tests-that-cannot-fail`: appending would have
+pushed that page past its one-case scope (test code → documents) and mixed two
+trigger sets in one "When this applies". They merged with _each other_ because
+they share one situation — writing a checker whose subject is a document — which
+is why 5 candidates produced 2 pages, not 5.
+
+**Related-links added:**
+`testing-docs-as-spec-document-conformance-checks` → `testing-quality-tests-that-cannot-fail`,
+`testing-quality-minimum-case-set`, `qa-process-acceptance-criteria`.
+`backend-common-storage-object-key-persistence` → `backend-common-api-design-idempotency`
+(backfill retry behaviour), `backend-node-boundaries-runtime-validation`.
+All five ids verified to resolve to existing files; no duplicate ids in `wiki/`.
 
 ## Routing decision
 
-- Target: **`databases/query-optimization/streaming-large-result-sets.md`** (new page).
-- Category `query-optimization` fits (memory-bounding how a query's result is pulled into the app is query-execution optimization); no new category needed.
-- Registered in `databases/index.md` (query-optimization section) and appended to `log.md`.
+### 1. `wiki/testing/docs-as-spec/document-conformance-checks.md` — NEW category
+
+- **Domain `testing`** over `qa` (two candidates were tagged `qa`): the artifact
+  being authored is an automated check, which `INDEX.md` routes to testing; `qa`
+  is scoped to release _process_. Routing by "which artifact do you change"
+  (AGENTS.md step 1) puts it in testing.
+- **New category `docs-as-spec`** rather than `quality`. Every existing testing
+  category — strategy, quality, data, mocking, flaky, async, e2e — is organized
+  around testing _executable code_, and their mechanics (assertions, fixtures,
+  fake timers, selectors) do not apply when the subject is a Markdown document.
+  Filing under `quality` would have made the "load when" line collide with
+  `tests-that-cannot-fail`'s, which is the drift condition AGENTS.md invariant 1
+  warns about. Single-page categories are already the norm here (`async`, `e2e`,
+  `data`, `mocking`, `flaky` each hold one page).
+- Index updates: new section in `wiki/testing/index.md` with a "load when" line
+  enumerating all four distinct uses (authoring the check pre-document; choosing
+  the mutation; a gate that passed on a degraded document; Markdown table
+  parsing); testing's "Route here for" preamble and the root `INDEX.md` testing
+  row both extended with "checks whose subject is a document rather than code".
+
+### 2. `wiki/backend/common/storage/object-key-persistence.md` — NEW category
+
+- **Domain `backend`, subtree `common`** rather than `node`. The directive
+  ("persist the identifier the service documents as canonical; derive URLs at
+  read time") is language-agnostic and reproduces in v2 and v3 — AGENTS.md says
+  common owns the principle and the stack page owns the mechanics, and there are
+  no Node-runtime mechanics here beyond the SDK field names.
+- **New category `storage`.** The eight existing `common/` categories are
+  api-design, reliability, caching, jobs, errors, auth, orm, concurrency —
+  none covers object storage. `api-design` is about this service's own contract,
+  not a dependency's response shape; `orm` is DB persistence.
+- Index updates: new `### storage` section in `wiki/backend/index.md` (placed
+  before `reliability`), plus "object-storage references" added to the `common`
+  subtree route line and to the backend row of the root `INDEX.md`.
+
+## Invariants checked
+
+- Body length: 73 and 60 lines (limit 120).
+- Every `related:` id resolves; no duplicate ids across `wiki/`.
+- Both pages listed in their domain `index.md`; both domains in `INDEX.md`.
+- Two `## [2026-07-30] ingest` entries appended to `log.md`.
+- Positive guidance only: every "don't" lives in an `Instead of` row paired with
+  its replacement and a why.
+- Table cell counts re-verified with the unescaped-pipe splitter this PR
+  documents.
diff --git a/INDEX.md b/INDEX.md
index 05789bd..e12a17d 100644
--- a/INDEX.md
+++ b/INDEX.md
@@ -10,10 +10,10 @@ follow the cross-pointers in their index or take the next matching seeded domain
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
 | [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior |
-| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps) |
+| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, object-storage references) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility |
 | [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting) |
-| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
+| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests, checks whose subject is a document rather than code (release-process quality → qa) |
 | [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, exploratory testing (writing automated test code → testing) |
 | [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
 | [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene, dependency trust, PII handling (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
diff --git a/log.md b/log.md
index 587a5dc..3f66362 100644
--- a/log.md
+++ b/log.md
@@ -34,3 +34,5 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-07-12] revise | security/secrets-in-code +1 edge case: third-party HTTP client (httpx/requests) logs the full request URL — including a query-param API key — at INFO, so root/DEBUG logging leaks it; keep the client logger above INFO. Found when a standalone sync process set logging.basicConfig(INFO) and httpx wrote the data.go.kr serviceKey to the log file. last_verified bumped to 2026-07-12.
 ## [2026-07-13] ingest | databases +1 (query-optimization): streaming-large-result-sets — memory-bounded export of a huge single-query result. Client-side cursor pulls the whole set to libpq on execute (fetchmany caps only the Python-list explosion); only a server-side/named cursor truly streams but needs a transaction, so it fails under autocommit or a proxy that blocks BEGIN → fall back to client-side fetchmany + disk spool + openpyxl write_only (measured 300k rows 838MB→38MB). Derived from RNR-3440 (potential-listing weekly extract memory peak); QueryPie BEGIN-block generalized to "read-only access proxy", field-tested. Sources: psycopg2 usage/cursor docs (named-cursor WITHOUT HOLD + autocommit exception), openpyxl optimized-modes (write-only near-constant memory, lxml=speed-not-memory).
 ## [2026-07-23] ingest | databases +2: schema-design/online-schema-changes (ACCESS EXCLUSIVE lock avoidance — non-volatile default fast path, ADD CONSTRAINT NOT VALID + VALIDATE at SHARE UPDATE EXCLUSIVE, CHECK-NOT-NULL trick, CREATE INDEX CONCURRENTLY, expand-and-contract to decouple DB migration from app deploy, lock_timeout for lock-queue pile-up) + operations/autovacuum-and-wraparound (NEW category operations: per-table scale_factor/cost_limit tuning for hot tables, age(datfrozenxid)/relfrozenxid + n_dead_tup monitoring, wraparound read-only cliff and superuser VACUUM recovery, VACUUM FULL vs pg_repack). Derived from the Hatchet "Postgres survival guide"; both cross-checked against PostgreSQL official docs (sql-altertable, routine-vacuuming).
+## [2026-07-30] ingest | testing +1 (NEW category docs-as-spec): document-conformance-checks — positive+negative control per check for gates whose subject is a document; validate the pattern on a conforming sibling when the target file does not exist yet (absence makes every pattern red); four-axis split (structure / normative modality / enum row completeness / cross-reference) each with a mutation that breaks only what it owns; coverage vs value-validity as separate checks; GFM unescaped-pipe row splitting. Folded from 4 queued insights (grep-gate falsifiability, spec-gate blind spots, coverage-vs-correctness, markdown table parsing) — one situation, one page. Sources: ESLint RuleTester valid/invalid, Semgrep ruleid/ok, Google mutation testing, JSON Schema required, GFM tables spec.
+## [2026-07-30] ingest | backend +1 (NEW category common/storage): object-key-persistence — persist the upload response Key (+Bucket) and derive URLs on read; Location is produced by two different code paths split at the managed uploader part size (5 MiB default), so one column ends up holding percent-encoded and form-encoded keys and only multipart rows 404. Derived from an RTB presigned-URL regression; verified against S3 CompleteMultipartUpload API docs, ManagedUpload docs, aws-sdk-js managed_upload.js source, and issues #1158 (v2) / #5656 (v3).
diff --git a/wiki/backend/common/storage/object-key-persistence.md b/wiki/backend/common/storage/object-key-persistence.md
new file mode 100644
index 0000000..c756cd7
--- /dev/null
+++ b/wiki/backend/common/storage/object-key-persistence.md
@@ -0,0 +1,75 @@
+---
+id: backend-common-storage-object-key-persistence
+domain: backend
+category: storage
+applies_to: [aws-s3, aws-sdk-js-v2, aws-sdk-js-v3]
+confidence: verified
+sources:
+  - https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html
+  - https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3/ManagedUpload.html
+  - https://github.com/aws/aws-sdk-js/blob/master/lib/s3/managed_upload.js
+  - https://github.com/aws/aws-sdk-js/issues/1158
+  - https://github.com/aws/aws-sdk-js-v3/issues/5656
+last_verified: 2026-07-30
+related: [backend-common-api-design-idempotency, backend-node-boundaries-runtime-validation]
+---
+
+# Persisting the Result of an Object-Storage Upload
+
+## When this applies
+
+You are writing the result of a managed/multipart object-storage upload
+(`s3.upload()`, `@aws-sdk/lib-storage` `Upload`, an equivalent transfer manager)
+into a database column, a message, or any store read back later — and you are
+choosing which response field to persist.
+
+## Do this
+
+1. **Persist the raw object key (`Key`) plus the bucket, and derive URLs at read
+   time.** `Key` is the field the service documents as "the object key of the
+   newly created object" and is what every later call (`GetObject`,
+   `getSignedUrl`, `HeadObject`, delete) takes as input.
+2. **Treat `Location` as display-only.** Its encoding and host are not a
+   documented contract, and the value comes from a different producer on each
+   upload path:
+
+| Upload path | Taken when | Who produces `Location` | Observed form |
+|-------------|------------|-------------------------|---------------|
+| Single part (`PutObject`) | Body ≤ the managed uploader's part size — 5 MiB (5,242,880 B) by default in aws-sdk-js | The SDK, joining `protocol + host + httpRequest.path` | Path-style percent-encoding: space → `%20` |
+| Multipart (`CompleteMultipartUpload`) | Body over that threshold | The S3 response, passed through after the SDK rewrites `%2F` back to `/` | Service encoding with only slashes repaired: space → `+` survives |
+
+3. **Build the read path from `Key`.** Sign or fetch with the stored key exactly
+   as stored; apply no decode step. A stored key needs no repair, so no decode
+   rule has to be guessed later.
+4. **When a column already holds URLs, migrate by extracting the key** — reverse
+   both encodings by upload size, verify each candidate with `HeadObject`, and
+   write `Key` back. Add the `Key` column before the code switch so old and new
+   rows are both readable ([backend-common-api-design-idempotency] for the
+   backfill's retry behavior).
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| A CDN or custom domain fronts the bucket | Store `Key` and compose `cdnBase + encodeURI(key)` at read time; in aws-sdk-js-v3 the multipart path returns the origin host in `Location` while the single-part path returns the custom domain (issue #5656) |
+| The key contains `+` as a literal character | Storing `Key` keeps it literal; a URL round-trip cannot distinguish it from an encoded space, which is why the encoded form is not a safe identifier |
+| A bug report says "only large files 404" | Read it as the single-part/multipart split, not as intermittency: the threshold is a deterministic byte boundary, so reproduce at part-size ± 1 byte |
+| Only `Location` was ever stored and the objects must be found now | Try both decodings per row (`+` → space and `+` literal), confirm with `HeadObject`, and record which rows stayed ambiguous |
+| `partSize` is configured above the default | The boundary moves to that value; read it from the uploader config rather than assuming 5 MiB |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Save `uploadRes.Location` as the object's identifier | Save `uploadRes.Key` (with `Bucket`) and build URLs on read | `Location` is produced by two different code paths with two different encodings, so one column ends up holding both |
+| Add a `decodeURIComponent` on read to fix the broken rows | Store the raw key so the read path needs no decode | Standard URL decoding leaves `+` as a literal, so it repairs the single-part rows and leaves the multipart rows 404-ing |
+| Chase the mismatch as a nondeterministic uploader bug | Compare file sizes against the uploader's part size and reproduce at the boundary | The behaviour is decided by one byte-size comparison; naming it "intermittent" sends the fix to the upload layer instead of the persistence layer |
+| Normalize the encoding inside the upload wrapper | Change what the caller persists | The wrapper cannot fix rows already written, and the service keeps returning its own `Location` regardless |
+
+## Sources
+
+- https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html — response elements: `Key` is "the object key of the newly created object"; `Location` is documented only as "the URI that identifies the newly created object", with no encoding guarantee
+- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3/ManagedUpload.html — callback data carries `Location`, `ETag`, `Bucket`, `Key`; `AWS.S3.ManagedUpload.minPartSize = 1024 * 1024 * 5` and the default `partSize` is 5 MB
+- https://github.com/aws/aws-sdk-js/blob/master/lib/s3/managed_upload.js — `finishSinglePart` builds `data.Location` from `endpoint.protocol + '//' + endpoint.host + httpReq.path` and sets `data.Key` from `params.Key`; `finishMultiPart` takes the service's `Location` and applies only `.replace(/%2F/g, '/')`
+- https://github.com/aws/aws-sdk-js/issues/1158 — reported inconsistency: multipart returns `…/stream-uploads%2Fkokoko.gif` where single-part returns `…/stream-uploads/kokoko.gif`; `Key` is identical in both responses
+- https://github.com/aws/aws-sdk-js-v3/issues/5656 — same split in v3 `lib-storage`: `__uploadUsingPut` constructs `Location` client-side, `CompleteMultipartUploadCommand` does not
diff --git a/wiki/backend/index.md b/wiki/backend/index.md
index e991b04..7a38e89 100644
--- a/wiki/backend/index.md
+++ b/wiki/backend/index.md
@@ -5,7 +5,7 @@ three stack subtrees — route by concern first, stack second:
 
 | Subtree | Route there when |
 |---------|------------------|
-| [common](#common-language-agnostic) (below) | The concern is language-agnostic: API contracts, idempotency, JWT issuance, outbound calls, caching, jobs, transactions in app code, shared state/pools, exception structure |
+| [common](#common-language-agnostic) (below) | The concern is language-agnostic: API contracts, idempotency, JWT issuance, outbound calls, caching, jobs, transactions in app code, shared state/pools, exception structure, object-storage references |
 | [java](java/index.md) | You are writing/reviewing JVM backend code (Java/Kotlin, Spring, JPA/Hibernate) and the concern is stack-specific: entity mapping, persistence context, proxy pitfalls, JVM threads/memory |
 | [node](node/index.md) | You are writing/reviewing Node.js/TypeScript backend code: event-loop blocking, promise error handling, runtime validation at boundaries, graceful shutdown |
 | [python](python/index.md) | You are writing/reviewing Python backend code: GIL/concurrency model, pydantic validation, WSGI/ASGI workers, language traps |
@@ -26,6 +26,12 @@ Match your situation to a "load when" line; load only matching pages.
 | [idempotency](common/api-design/idempotency.md) | An endpoint with side effects (create, charge, send) can receive the same request twice — client retry after timeout, user double-submit, gateway retry; designing idempotency-key storage; deciding which operations are safe to retry |
 | [pagination-contract](common/api-design/pagination-contract.md) | Designing a list endpoint's request/response contract — cursor vs page-number, limit caps, total counts, expired-cursor behavior (the backing SQL/index → databases/query-optimization/keyset-pagination) |
 
+### storage
+
+| Page | Load when |
+|------|-----------|
+| [object-key-persistence](common/storage/object-key-persistence.md) | Persisting the result of an object-storage upload (`s3.upload()`, `lib-storage` `Upload`, a transfer manager) — choosing which response field goes in the DB column; building the read/signing path from a stored reference; migrating a column that holds URLs to keys; only large uploads 404 on read |
+
 ### reliability
 
 | Page | Load when |
diff --git a/wiki/testing/docs-as-spec/document-conformance-checks.md b/wiki/testing/docs-as-spec/document-conformance-checks.md
new file mode 100644
index 0000000..677d314
--- /dev/null
+++ b/wiki/testing/docs-as-spec/document-conformance-checks.md
@@ -0,0 +1,88 @@
+---
+id: testing-docs-as-spec-document-conformance-checks
+domain: testing
+category: docs-as-spec
+applies_to: [general]
+confidence: verified
+sources:
+  - https://eslint.org/docs/latest/integrate/nodejs-api#ruletester
+  - https://docs.semgrep.dev/writing-rules/testing-rules
+  - https://testing.googleblog.com/2021/04/mutation-testing.html
+  - https://json-schema.org/understanding-json-schema/reference/object
+  - https://github.github.com/gfm/#tables-extension-
+last_verified: 2026-07-30
+related: [testing-quality-tests-that-cannot-fail, testing-quality-minimum-case-set, qa-process-acceptance-criteria]
+---
+
+# Checking a Document Against Its Spec
+
+## When this applies
+
+You are writing or reviewing an automated check whose subject is a **document** —
+an RFC, API spec, schema doc, mapping table, ADR — and the check decides whether
+that document satisfies stated requirements (grep gate, parse script, CI step).
+Includes checks authored before the document they will judge exists.
+
+## Do this
+
+1. **Give every check two controls, and run both before adopting it.** This is the
+   rule linters apply to their own rules: ESLint `RuleTester` requires a `valid`
+   and an `invalid` array; Semgrep rule tests require `ok:` (true negative) and
+   `ruleid:` (true positive) lines. A check that has run against only one of the
+   two is unproven.
+
+| Control | Input | Required result | What it proves |
+|---------|-------|-----------------|----------------|
+| Positive | A document that already conforms — the sibling spec written to the same template | PASS, with the exact expected count (`7` sections, `2` matches), not merely exit 0 | The pattern, anchors, and escaping are correct |
+| Negative | A copy of that conforming document with exactly one requirement broken | FAIL, naming that requirement | The check detects the defect it owns |
+
+2. **When the target document does not exist yet, take the positive control from a
+   conforming sibling.** A missing file makes every pattern red, so red is
+   evidence about the file's absence, not about the pattern. A typo'd or
+   mis-anchored pattern produces the same red and becomes a gate that fails
+   forever once the document is written.
+
+3. **Split the requirement into axes and give each axis its own check and its own
+   negative control** — one mutation that breaks only what that check owns:
+
+| Axis | The check | Its negative control |
+|------|-----------|----------------------|
+| Structure | Parse the table: row count, column count per row, no empty cells | Delete the whole table, leaving the surrounding prose intact |
+| Normative modality | The required/optional column values and the obligation sentence in prose | Flip one `required` cell to `optional` |
+| Enumeration completeness | The enum table has exactly N rows, one per canonical case | Delete one row |
+| Cross-reference | Every identifier cited here resolves in the document it points at | Replace one identifier with a nonexistent one |
+
+4. **Pair every coverage check with a value-validity check.** Coverage answers
+   "is there a row for each required item"; validity answers "is each cell's value
+   a member of the canonical enum / schema / id set". JSON Schema draws the same
+   line: `required` asserts key presence and constrains no value. Run each as a
+   separate check so the failure message says which one broke.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The check parses Markdown table rows | Split on unescaped pipes — `re.split(r"(?<!\\)\|", row)` — then unescape `\|` in each cell before counting. GFM permits a literal pipe in a cell when escaped, including inside code spans (`create\|update\|delete`) |
+| No conforming sibling exists (first document of its kind) | Hand-write a 10-line fixture that satisfies the requirement, use it as the positive control, and keep it next to the check |
+| A negative control passes | The check is decoration: fix it against that mutation, then re-run both controls before adopting |
+| Prose and table state the same requirement | Check the table (machine-readable, load-bearing) and cross-check that the prose sentence exists; a prose-only match is not evidence the table survived |
+| The subject is code, not a document | The general mutate-and-require-red rule → [testing-quality-tests-that-cannot-fail] |
+| Requirements are still being drafted | Fix the requirement wording first → [qa-process-acceptance-criteria]; a check cannot be more precise than the requirement it encodes |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Accept a pattern because it exits non-zero against the not-yet-written document | Run it against a conforming sibling and require the exact expected count | Absence makes every pattern red, a typo'd one included; the gate then fails forever once the document lands |
+| Verify a requirement with one token-presence grep | Add the structural and value checks for that requirement, each with its own negative control | The token survives in prose after the table it came from is deleted, so the gate passes on a document that lost the requirement |
+| Read a green coverage check ("every rule has a row") as "the mapping is verified" | Add a value-validity check: each cell's value must exist in the canonical enum/id set | Set equality on row names is blind to cell contents — a typo'd, empty, or swapped value keeps coverage at 100% |
+| Prove an `Examples` section demonstrates a rule and stop there | Check the normative statement itself (the required/optional cell, the obligation sentence) | Examples keep matching after the rule that mandates them is relaxed, so the example check reports green on a weakened spec |
+| Split Markdown rows with `split("\|")` | Split on unescaped pipes, then unescape each cell | `\|` is legal cell content, so a naive split reports a correctly rendering row as over-wide and buries real breakage in false alarms |
+
+## Sources
+
+- https://eslint.org/docs/latest/integrate/nodejs-api#ruletester — `RuleTester` takes `valid` and `invalid` case arrays; invalid cases must assert the errors the rule is expected to produce
+- https://docs.semgrep.dev/writing-rules/testing-rules — rule tests annotate true positives (`ruleid:`) and true negatives (`ok:`) in the same test file
+- https://testing.googleblog.com/2021/04/mutation-testing.html — inserting a fault and requiring the check to fail measures detection; coverage alone does not
+- https://json-schema.org/understanding-json-schema/reference/object — `required` lists properties that must be present and places no constraint on their values
+- https://github.github.com/gfm/#tables-extension- — cells are separated by pipes; "include a pipe in a cell's content by escaping it, including inside other inline spans"
diff --git a/wiki/testing/index.md b/wiki/testing/index.md
index 78418d7..73b7cdc 100644
--- a/wiki/testing/index.md
+++ b/wiki/testing/index.md
@@ -3,9 +3,9 @@
 Route here for: writing or structuring automated tests — choosing the test
 level, selecting cases and assertions, test data and isolation, mock/fake
 decisions, fixing flaky tests, verifying tests can actually fail, testing
-async code (promises/timers/events), and browser E2E selector/wait/setup
-strategy. Release-process quality (gates, manual testing, bug triage) →
-wiki/qa/.
+async code (promises/timers/events), browser E2E selector/wait/setup
+strategy, and checks whose subject is a document rather than code.
+Release-process quality (gates, manual testing, bug triage) → wiki/qa/.
 
 Match your situation to a "load when" line; load only matching pages.
 
@@ -23,6 +23,12 @@ Match your situation to a "load when" line; load only matching pages.
 | [behavior-not-implementation](quality/behavior-not-implementation.md) | Deciding what a test should assert; a behavior-preserving refactor broke tests; tempted to expose privates for testing; deciding whether a snapshot test is appropriate |
 | [tests-that-cannot-fail](quality/tests-that-cannot-fail.md) | Reviewing tests that always pass; a bug shipped through an area the suite reported as covered; auditing a suspiciously green suite; judging whether an assertion, error-path test, or mock-based test can actually detect a defect |
 
+## docs-as-spec
+
+| Page | Load when |
+|------|-----------|
+| [document-conformance-checks](docs-as-spec/document-conformance-checks.md) | Writing or reviewing an automated check whose subject is a document (RFC, API spec, schema doc, mapping table, ADR) — grep gates, parse scripts, CI doc gates; authoring the check before the document exists; deciding what to mutate to prove the check can fail; a doc gate passed on a document that lost a requirement; parsing Markdown tables (cell counts, per-column extraction) programmatically |
+
 ## data
 
 | Page | Load when |

From 5495be87b36d7880c1f1f8b1c22667441c7db72e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=B5=9C=EC=98=81=EA=B8=B0?= <dch0202@rsquare.co.kr>
Date: Thu, 30 Jul 2026 11:48:52 +0900
Subject: [PATCH 2/3] knowledge: record cross-check scope in ingest report

---
 .dev-loop/INGEST_REPORT.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.dev-loop/INGEST_REPORT.md b/.dev-loop/INGEST_REPORT.md
index bf984cb..84e6fe1 100644
--- a/.dev-loop/INGEST_REPORT.md
+++ b/.dev-loop/INGEST_REPORT.md
@@ -168,6 +168,20 @@ All five ids verified to resolve to existing files; no duplicate ids in `wiki/`.
   before `reliability`), plus "object-storage references" added to the `common`
   subtree route line and to the backend row of the root `INDEX.md`.
 
+## Cross-Check
+
+Cross-Check: source-level, not adversarial-reviewer. Every claim in this PR was
+re-derived in-session from the primary source rather than from the harvested
+candidate text — five docs/issues fetched for the S3 page (including reading
+`managed_upload.js` on `raw.githubusercontent.com` instead of trusting the
+candidate's line numbers) and four for the doc-gate page, with two independent
+tools (ESLint `RuleTester`, Semgrep rule tests) converging on the
+positive+negative control requirement. The pipe-splitting rule was reproduced
+against this PR's own two pages. One candidate claim was downgraded on review
+(the `space → +` multipart form is field evidence, not a documented contract —
+see the scope correction above). No separate adversarial reviewer ran; the
+owner's PR review is the remaining gate.
+
 ## Invariants checked
 
 - Body length: 73 and 60 lines (limit 120).

From dcfd2cc248fda2e99d9208e70bcaefaa6b67d4bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=B5=9C=EC=98=81=EA=B8=B0?= <dch0202@rsquare.co.kr>
Date: Thu, 30 Jul 2026 11:49:43 +0900
Subject: [PATCH 3/3] knowledge: add decision log to ingest report

---
 .dev-loop/INGEST_REPORT.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/.dev-loop/INGEST_REPORT.md b/.dev-loop/INGEST_REPORT.md
index 84e6fe1..ba0f221 100644
--- a/.dev-loop/INGEST_REPORT.md
+++ b/.dev-loop/INGEST_REPORT.md
@@ -182,6 +182,32 @@ against this PR's own two pages. One candidate claim was downgraded on review
 see the scope correction above). No separate adversarial reviewer ran; the
 owner's PR review is the remaining gate.
 
+## Decision Log (AI 생성)
+
+### 의도 — 무엇을 / 왜
+
+- 큐에 쌓인 5개 후보를 각각 원본 1차 소스로 재검증한 뒤 wiki 2페이지로 적재했다. 후보 텍스트를 그대로 믿지 않고 ESLint/Semgrep/GFM/JSON Schema/AWS 문서와 `managed_upload.js` 소스를 직접 열어 대조했다 — 수확된 블록은 후보이지 검증된 지식이 아니기 때문.
+- 5후보 → 2페이지로 접었다. AGENTS.md "one case per page"는 후보 수가 아니라 **상황** 단위로 자르므로, 1·2·4·5는 모두 "문서를 대상으로 하는 체커를 작성하는 상황" 하나라 한 페이지로 병합했다.
+- 새 카테고리 2개(`testing/docs-as-spec`, `backend/common/storage`)를 만들었다. 기존 카테고리는 각각 "코드 테스트"와 "8개 common 관심사"로 짜여 있어 문서 검증·오브젝트 스토리지를 담을 자리가 없었다.
+
+### 배제한 대안 — 무엇을 안 했나 / 왜
+
+- `testing/quality/tests-that-cannot-fail.md`에 append하지 않았다. 그 페이지는 *테스트 코드*의 mutation 규칙을 소유하고 "load when" 라인이 충돌해 AGENTS.md invariant 1의 drift 조건에 걸린다. 대신 양방향 링크로 연결.
+- 후보 2·5가 `domain: qa` 태그였지만 qa로 라우팅하지 않았다. qa는 릴리즈 *프로세스* 스코프이고, 여기서 만드는 산출물은 자동 체커라 testing이 소유한다.
+- 후보 3을 `backend/node`가 아닌 `backend/common`에 뒀다. v2·v3 양쪽에서 재현되고 원리가 언어 무관이라, "common이 원리·stack이 메커닉"이라는 AGENTS.md 규칙에 따랐다.
+- 후보 3의 "space → `+`"를 문서화된 계약으로 단정하지 않았다. 공개 소스로 확인되는 건 `/` → `%2F`뿐이라 컬럼명을 "Observed form"으로 두고 스코프를 좁혔다.
+- 포매터(PostToolUse prettier)가 index 3개 파일의 표 전체를 패딩해 무관한 행까지 diff에 올렸다 — 되돌리고 스크립트로 대상 라인만 재적용했다(INDEX.md 2줄, backend +8/-1, testing +12/-3).
+
+### 리뷰어가 볼 곳 — 신뢰성 판단 포인트
+
+- `.dev-loop/INGEST_REPORT.md` "Verified best-practice" — 인용 URL이 실제로 그 주장을 지지하는지. 특히 "One scope correction" 문단(후보보다 약하게 적은 부분).
+- `wiki/testing/docs-as-spec/document-conformance-checks.md:39-42` — positive/negative control 표. ESLint valid/invalid + Semgrep ok/ruleid 두 출처가 실제로 이 형태를 강제하는지.
+- `wiki/backend/common/storage/object-key-persistence.md:40-43` — 단일/멀티파트 인코딩 표. "Observed form" 열이 문서화된 계약처럼 읽히지 않는지.
+- `wiki/testing/index.md`, `wiki/backend/index.md` — 새 "load when" 라인이 인접 페이지 트리거와 겹치지 않는지(AGENTS.md invariant 1).
+- 새 카테고리 2개 신설이 과한지 — 기존 카테고리로 접는 게 낫다고 보면 이 PR에서 되돌리기 쉬운 부분.
+
+> [추정] 표시 항목은 세션에 명시 근거가 없어 사후 재구성한 의도임 — 검증 필요
+
 ## Invariants checked
 
 - Body length: 73 and 60 lines (limit 120).