GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
`# Computation` is a conventional heading in §4.2 and the sole locator of the computation in §10
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§4.2 introduces the heading as optional convention:
> There are no required body sections. The following headings have **conventional** meaning and SHOULD be used when applicable:
with `# Computation` listed in the table beneath it. §13.2 repeats the framing, listing "New conventional body heading `# Computation` (§4.2)" among the additive changes.
§10 then makes that exact literal heading load-bearing. §10.2:
> `computation`: Optional. A path (§6.2) to a file holding the computation, used instead of an inline body fence (see §10.3). Absent ⇒ the body `# Computation` fence is the computation.
and §10.3:
> **Inline:** a single fenced code block in the body under `# Computation`.
So when `computation` is unset, which is the case in every Attested Computation in this repo, a heading the spec calls conventional is the only thing that says which fenced block a consumer should run.
## Why it matters
The spec gives no grammar for the heading. Nothing states the heading level, so a producer writing `## Computation` is following the convention as described and may still be unreadable to a consumer matching on `# Computation`. Nothing says what to do when the section contains more than one fenced block, though §10.3's "a single fenced code block" implies more than one is wrong. Nothing says whether an indented block counts, which #235 raises from the other direction, since §10.2's own example indents rather than fences.
These are the parsing decisions that determine which SQL runs. §10.3 argues that a typed, parameter-only surface makes "did the sanctioned thing run" a mechanical comparison. That holds only if producer and consumer locate the computation the same way, and right now the locating rule sits in a section that describes itself as convention.
## Suggestion
Move the locating rule into §10 as normative text: the heading string, the accepted heading levels, what counts as the block, and what a consumer does when the section holds none or several. §4.2 can keep listing `# Computation` as conventional for readers, provided §10 states that for `type: Attested Computation` it is the required locator. That's a small edit for something the attestation guarantee rests on.
Contributor guide
Research direction
Read §4.2, §10, and §13.2, along with the related concern in #235. Define normative rules for the computation heading, accepted levels, block selection, and zero-or-multiple-block cases; done means §10 unambiguously determines what consumers execute while §4.2 remains reader-facing convention.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100