gnomonlearn
Docs/RFC-0011/Design Q&A

RFC-0011 · Design Q&A

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

← Read the authored RFC

Q: How do decorators compose with the base grammar, and what does an older parser do?

A: RFC-0008 owns one integrated top-level-decl rule. RFC-0011 contributes annotation-specific productions. A decorated declaration requires one or more decorators followed by an undecorated target, so it cannot match an empty decorator sequence or recurse into another decorated declaration. An older parser rejects unsupported annotation syntax with M11803, naming the required compiler version or feature; it does not silently discard annotations or a declaration.

Where normative: §4 and §10 of RFC-0011; §8.2 of RFC-0008

Q: Which declaration bodies accept an inline annotations {} block?

A: The eleven open-body kinds listed in RFC-0008 §6.0: entity, type, action, policy, agent, claim, query, view, model, annotation facet, and annotation aspect. Each has an explicit grammar binding and permits at most one inline block. Unbraced import and apply, expression-only invariant, and other bodies without a binding do not accept it.

Where normative: §4.1–§4.4 of RFC-0011; §6.0 and §8 of RFC-0008

Q: Should annotation schema declarations be scoped per module or per project?

A: Module-scoped. Each module declares its own annotation schema block listing the annotation facets it recognizes and validates. Teams that want project-wide schema consistency SHOULD extract their annotation facets into a shared gnomon.core-style library module and import it everywhere.

Where normative: §3 (annotation schema scoping) of RFC-0011

Q: Should annotation predicates in annotation aspect support arbitrary expr conditions?

A: No, not in the initial spec. The annotation predicate language (§4.3) supports includes, fields contains, and and combinators only. Arbitrary expr conditions would require the full expression evaluator to run at annotation-merge time, which is earlier in the compile pipeline than expression evaluation normally occurs. Arbitrary predicates are deferred until there is concrete evidence from real usage that the restricted predicate language is insufficient.

Where normative: §4.3 of RFC-0011

Q: Should there be a built-in annotation facet for common governance keys?

A: Yes. The gnomon.core library module MUST provide a standard @Governance annotation facet with keys owner: String, domain: String, since: String, and deprecated: Boolean. Projects that use gnomon.core get these for free. The @Governance facet is not mandatory; declaring it is an opt-in through the gnomon.core import.

Where normative: §5 (built-in facets) of RFC-0011

Q: Should annotation values be queryable via the gnomon query API at runtime?

A: Compile-time and bundle-metadata only in the initial spec. Annotation values are stored in the compiled bundle’s composition_envelopes and are accessible to the LSP, compiler services, and documentation tooling. They are NOT queryable through the gnomon.find() / gnomon.resolve() runtime query API (RFC-0007). This may be revisited in a future RFC if runtime annotation inspection is found to be necessary.

Where normative: §6 (annotation storage) of RFC-0011