gnomonlearn
Docs/RFC-0008/Design Q&A

RFC-0008 · 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: Should entity syntax and scope syntax ultimately converge into a single unified surface?

A: Unified in this revision. All declarations use a single open block-property syntax.

Where normative: §8 (declaration syntax) of RFC-0008

Q: Should agent declarations be a compile-time only concern, or do they produce runtime-registered capability objects?

A: Two-layer model. The agent declaration is a compile-time capability contract specifying purpose, inputs, outputs, permissions, and prohibitions. A separate binding declaration (RFC-0015) maps an agent to a runtime endpoint, model provider, and configuration. The agent declaration in §8.10 remains unchanged; the full binding specification is in RFC-0015.

Where normative: §8.10 of RFC-0008

Q: How should AI-assisted authoring be surfaced in the language?

A: The draft epistemic modifier (§11.2) is the normative AI authoring marker. AI agents MUST attach draft to any declaration that has not been reviewed by a human author (RFC-0009 §6). See §11.2 for compiler enforcement and M08780/M08786 diagnostics.

Where normative: §11.2 of RFC-0008

Q: Should the EBNF grammar be machine-verified against the parser implementation as a CI step?

A: Yes, normative. See §8.0.

Where normative: §8.0 of RFC-0008

Q: Should the one-line query shorthand be retained or deprecated?

A: Retained as sugar. See §8.21.

Where normative: §8.21 of RFC-0008

Q: Should the language define a set of declaration-level epistemic markers?

A: Yes. draft, deprecated, experimental, sealed, abstract are defined in §11.2 as epistemic-modifier, added to the shared decl-modifier production in §8.22. Grammar, semantics, and diagnostics M08780–M08786 are specified there.

Where normative: §11.2 of RFC-0008

Q: Should meaning and /// doc comment values be validated as CommonMark at compile time?

A: Yes, warning-only. DOC-COMMENT blocks and meaning field values MUST be valid CommonMark; violations produce warning M08760 and M08761 respectively. The compiler MUST NOT fail on invalid CommonMark; warnings are advisory and do not block compilation or CI.

Where normative: §8 (compiler diagnostics) of RFC-0008

Q: Should JSON Schema be a first-class output artifact of compilation?

Status: Open Context: Unspecified. RFC-0002 currently defines no jsonSchema compiled-bundle output target, generation rules, mapping from Gnomon types, or $defs structure. The existing graph-module schema command generates JSON Schema for YAML module-manifest validation, a separate source format and output contract. A future revision must specify the compiled-bundle target before it can be advertised as supported.

Where normative: n/a — pending future RFC or implementation experience

Q: Annotation system design.

A: Annotation facets, annotation aspects, @ decorator syntax, and the annotation resolution model are specified in RFC-0011.

Where normative: RFC-0011 (annotation system)

Q: RFC scope split.

A: RFC-0008 owns the base language surface and normative grammar. RFC-0011 owns the annotation system. RFC-0012 owns Gnomon tooling (gnomon fmt, compiler flags, CI). DESIGN.md is the non-normative design rationale companion.

Where normative: see RFC body of RFC-0008

Q: Does a file name identify the concept or the declaration kind?

Status: Open Issue: §4 says each file is named after the concept it defines, while §7 and §9.0 require fixed kind names such as schema.gnm and actions.gnm inside a concept-named folder. The compiler discovery table and M07902 depend on the fixed names. The recommended reconciliation is to name the folder after the concept and each file after its declaration kind, then amend the §4 sentence and the two affected Lean derivations. An owner decision is required because filename rules are part of the authoring contract. Acceptance: one rule across the prose, examples, grammar, diagnostics, compiler discovery, Lean catalog, and generated references, with a fixture for a multi-class concept folder.

Where normative: §4, §7, and §9.0 of RFC-0008; pending owner decision