GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Spec inconsistency: §10.3 says the inline computation is a fenced code block, but §10.2's example indents it
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§10.3 says an Attested Computation may carry its computation inline as *"a single fenced code block in the body under `# Computation`."* But §10.2's own worked example puts the computation in a **4-space-indented** code block, not a fence:
```markdown
# Computation
SELECT SUM(amount) AS revenue
FROM finance.recognized_revenue
WHERE fiscal_year = @year
```
A consumer that detects the inline computation by looking for a *fenced* block under `# Computation` — the literal §10.3 wording — would miss the spec's own example, and for the §10.3 "inline **or** a `computation:` path" rule would wrongly conclude the computation is provided in neither place.
## The question
Should §10.3 read "a fenced *or indented* code block," or should §10.2's example be rewritten as a fenced block? Either resolves it — the mismatch between the normative text and the worked example is the problem.
## Context
Same shape as #234 (the actor convention): the normative text and a worked example disagree, so a strict reading of one flags the other. This surfaced building the same structural validator; we currently key the inline-vs-path check on the presence of the `# Computation` heading rather than the code block's style, so both forms pass.
Contributor guide
Research direction
Compare the normative wording in §10.3 with the worked example in §10.2, focusing on the `# Computation` section and the inline-versus-`computation:` rule. Resolve the mismatch by making the specification and example use the same accepted code-block form, then verify that both forms are described consistently for structural validators.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100