docs(spec): reconcile interface sketches and layout with the code

[ekalinin]

Stacked on #19. Documentation only, no code changes.

spec.md gives interface sketches, and the implementation refined names and signatures as it went. The drift had accumulated to the point where the document contradicted itself: section 5.1 did not agree with section 7.

5.1 QueryService

Method names align with the RPC names in section 7 (GetQueryStatus, GetQueryStats, DownloadResult, WatchQuery), which is what keeps a transport a pure mapping. CanIBeStopped is added, along with the byte window on DownloadResult that backs both HTTP Range and the gRPC offset/limit. It now records that every read path resolves the record first and checks its subject, so a transport never has to know about authorization.

5.2 Drivers

Open takes a DSN string and a pool size - every supported driver parses the DSN itself anyway. RowStream reports column names rather than []ColumnMeta: none of the supported drivers offers portable type metadata before the first row.

5.3 ResultStore

Writer(ctx, queryID, format) returns the ResultRef instead of receiving one, because only the backend knows the locator it is about to write to. Register is called from main once the backend has been built from config rather than at init() time, since every backend needs configuration (a root directory, a bucket, a DSN). It records that Close on a writer is where S3 and ClickHouse wait for the upload or commit, so its error decides whether the query succeeded (I4).

12 Repository structure

Brought in line with the tree, including the two deliberate departures from the original sketch and the reasoning: idempotency has no package of its own (it is two MetaStore calls and a rollback inside SubmitQuery, and a package holding that would only move the sequencing away from the code that has to get it right), and internal/state is flat because redis and memory implement one interface and share its error values.

13 Stack

Records what the code actually depends on, including why the config layer is plain yaml.v3 with ${VAR} expansion rather than viper or koanf: a single file, an atomic snapshot swap and an explicit ReloadReport is the whole requirement, and neither library adds anything to it.

11 Telemetry

Describes the single metrics pipeline and the span link that stands in for the parent I1 makes impossible. It also notes that a series appears at its first observation rather than at startup, which is how OTel reports, so alerts must use rate() or increase() rather than absent().

Sections 9 to 14 shift to 10 to 15 to make room for the new Security section; the section references in code, in OpenAPI and in the proto are updated accordingly.