alpha-2027 · draft-alpha-2027 · tests/language/holesView source

Feature contract: hole#

(hole NAME) marks a position the program has not written yet (#119). It never elaborates. Checking it reports the GOAL -- the type the position needs and the binders in scope -- and fails, so a program is checked up to its holes and no artifact is ever built with a hole in it. The goal is the problem an agent (or a person) has to solve at that position, stated by the checker rather than reconstructed from the surrounding files.

1. Lexical and grammar rules, including precedence and termination#

A one-operand head whose operand is an identifier: (hole body). Anything else inside the parentheses (no name, a second name, a term) is ALPHA-PARSE-UNEXPECTED. An unterminated hole in a module is refused by the module reader before the term parser runs (ALPHA-MODULE-DEFINITION-CONTINUATION); the parser's own ALPHA-PARSE-HOLE ("unterminated hole") is reached only by a token stream with no end marker, which the lexer always appends, so no source file produces it.

2. Scope and binding rules, including generated names#

NAME binds nothing and refers to nothing; it labels the goal so several holes in one definition can be told apart. hole is a reserved head in every edition, as resolve and do are: a function or binder named hole is applied as (app hole x), and under alpha-2026 the edition gate refuses (hole x) (ALPHA-EDITION-UNSUPPORTED-FORM).

3. Type and quantity requirements#

The hole needs an expected type: the type of an annotated definition, a typed binder's domain, a function argument whose parameter type is known. Without one it is ALPHA-HOLE-NEEDS-TYPE. With one, it is ALPHA-HOLE-GOAL, whose message and structured detail state:

  • expected: the goal type, its local variables printed by name;
  • secondarySpans (alpha-diagnostic-v1; each entry's label): one entry per binder in scope, innermost first, each QUANTITY NAME : TYPE with the type printed in the binders outside it (a prophecy's ghost is marked ghost). Compiler-generated binders are omitted.

A reference to a module-level definition in a goal is printed by its qualified name, parenthesised: (equal Nat (M.limit) n).

4. Effects, totality, and evaluation-order rules#

None: a hole is refused before anything runs.

5. Elaboration into existing core or a specifically versioned new core extension#

None. A hole has no core form; the elaborator refuses it at its own position. The trusted core, erasure, ALRI and the checked-interface schema are unchanged.

6. Representation and target support, where relevant#

Not applicable: no artifact contains a hole.

7. Error codes and primary/secondary origins#

ALPHA-HOLE-GOAL (the goal) and ALPHA-HOLE-NEEDS-TYPE point at the hole; ALPHA-PARSE-HOLE at the unterminated form (unreachable from a source file, §1). Only the first hole the checker reaches is reported: elaboration of a definition stops at its first failure and alpha check stops at a module's first failing definition; fill or annotate it to see the next.

8. Formatting and migration rules#

Formatted as any one-operand head. No migration: no earlier program could contain the form.

9. Positive, negative, execution, and edge-case tests#

tests/language/holes, run by scripts/ci/typed-holes.sh: a goal with two binders of different quantities, an open proof whose goal names its binder, a hole with no expected type, the filled positive control, the alpha-2026 refusal, and the structured goal in alpha check --json. tests/language/draft/hole/ adds a goal naming a module-level definition, two holes of which only the first is reported, and a hole with two names. A hole under a prophecy's ghost is rendered by the same path but has no case yet.

10. Compatibility with the old edition, serialized forms, and cache keys#

alpha-2026 refuses the form at the edition gate, naming the hole. No serialized form, checked interface or cache key can contain a hole, since a module with one never checks. Reserving the head changes the meaning of (hole x) for a function named hole; no maintained source used one when it was reserved.

Known discrepancies and limits#

Candidate submission against a stable hole identity, a versioned query API over program identities, relevant-definition retrieval and goal dependencies (the rest of #119) are not implemented; neither are holes in types whose goal is a universe level, or proof-specific goal kinds.