Typical Computing

Intents

Intents are persistent, independently assessable natural-language statements about a program. An intent is part of the program rather than prose surrounding it: the compiler parses it, gives it stable identity and structural ownership, indexes its semantic relationships, and exposes it for analysis.

This structure creates an audit surface between what people said the program should do and what the implementation appears to do. Tools can evaluate one intent against relevant program context, display the result beside its evidence, or project a bird's-eye view of intents that appear supported, contradicted, inconclusive, stale, or not yet evaluated. The status vocabulary is tentative, but the distinction between these outcomes is part of the design.

Intent evaluation is probabilistic. An intent is not a compiler-enforced invariant, contract, test, declaration, or formal proof. A supported result means only that an evaluator found sufficient evidence in the context it inspected to judge the intent likely true. It does not establish that the complete program was exhaustively inspected or that no counterexample exists.

Intents are expected to be produced primarily by language models from spoken or written natural-language conversations. Any intent present in Typical source is authoritative and participates in auditing. An editor may use proposals, previews, or human approval before writing an extracted intent into source, but that workflow is not part of the language.

Terminology

A bullet fragment begins with -. A leaf bullet whose assembled text does not end with an unescaped question mark is an intent.

- Helps customers understand why a payment was declined

An unknown is a leaf bullet whose assembled text ends with an unescaped question mark.

- Should this cache expire after five minutes?

An unknown in intent syntax is unrelated to the compiler's internal unknowable recovery sentinel. An unknown records a natural-language question; unknowable short-circuits operations that cannot temporarily be compiled meaningfully.

An intent group begins with one through six # tokens.

# Customer experience
## Recovery

An invariant is a different language feature. Invariants are compiler behavior settings established with declare. Intents and unknowns do not alter compilation behavior in that manner.

Syntax

Intent syntax resembles a small part of Markdown, but it is not Markdown. The # tokens create intent groups, and - creates bullet fragments whose leaves are intents or unknowns. Other Markdown constructs, such as tables, are not supported by this syntax.

The marker occurs at the beginning of a new structural fragment and is followed by whitespace. This allows the parser to distinguish an intent marker from subtraction or a negative number.

An intent or unknown continues across subsequent lines while those lines are indented farther than the fragment where it began. This is the ordinary continuation rule used by the parser.

- Keeps saved work usable when (( Network )) is unavailable
    during a commute

Intent groups, intents, and unknowns may occur only at structural boundaries. They cannot interrupt expressions, parameter lists, or other fragments.

Bullet fragments may be nested to share sentence prefixes without repeating them. Each child continues the sentence fragment of its parent. Only leaf bullets are complete intents or unknowns; non-leaf bullets are structural fragments and are not independently evaluated.

- The checkout experience should
    - help customers
        - understand the total cost before payment
        - recover from correctable payment errors
    - avoid surprising returning customers with changed defaults

The example defines three intents: “The checkout experience should help customers understand the total cost before payment,” “The checkout experience should help customers recover from correctable payment errors,” and “The checkout experience should avoid surprising returning customers with changed defaults.” Each complete statement is assembled by reading the fragments along the spine from the outermost bullet to the leaf. Whitespace is normalized at fragment boundaries.

Ownership

Every bullet fragment and intent group has exactly one structural owner. Each leaf intent or unknown inherits that owner. Placement determines ownership. A semantic reference does not transfer or share ownership.

The implicit root space owns constructs written at the top level. The root space represents the complete program; source files do not independently own top-level intents.

The following constructs may own intents:

Imports, parameters, locals, and statements do not own intents.

An intent may precede an import because intents are permitted before the import block. The intent remains owned by the containing space; the import does not acquire it.

Spaces and other constructs with bodies contain their intents directly:

space App (
    - Keeps application startup understandable when initialization fails

    calculateThings() (
        - Gives recommendations that remain useful when customer history is sparse

        return 1 + 2 + 3
    )
)

Fields use their expanded parenthesized representation when they contain intents:

value = (
    12
    - Keeps ranking changes explainable when this confidence score changes
)

This serialized form keeps ownership explicit. The editor may project a field-owned intent above the field and visually collapse the wrapper, providing documentation-like ergonomics without changing the underlying ownership relationship.

Although locals share some field syntax, the editor does not expose intent ownership for locals.

Intent Groups

Intent groups form a hierarchy. A heading contains subsequent intent groups, intents, and unknowns according to its level.

# Customer confidence

- Explains the total before asking for payment

## Payment recovery

- Helps customers correct a declined payment without restarting checkout

The hierarchy remains within one structural owner. An intent group organizes semantic information; it does not create an executable language scope.

Any non-intent structural or executable fragment ends the active intent-group region. A later intent does not resume the earlier group automatically.

# Search quality

- Keeps the most useful results easy to find

doSomething()

- Avoids overwhelming customers with near-duplicate results

Only the first intent belongs to Search quality.

The token-based editor prevents skipped heading levels. If malformed raw text skips a level, the parser normalizes the heading to the next valid level. This is recovery for manually corrupted source rather than an expected authoring operation.

Intent groups may contain semantic references. References on an intent group become inherited semantic context for its descendant groups, intents, and unknowns.

# Customer trust for (( Network ))

- Keeps account activity private on shared networks
- Makes connection failures understandable and recoverable

The heading supplies Network as context for both intents. The intents do not need to repeat the reference. Conceptually, the compiler retains edges from the heading to Network and from the heading to its descendants. Retrieval of a descendant includes the semantic context of its heading ancestry.

The compiler does not enforce the natural-language coherence of a group and its descendants. Confusing or incoherent grouping may instead be surfaced by language-model analysis.

Unknowns

An unknown is recognized when the final meaningful token of the complete text assembled for a leaf is an unescaped ?.

- Should (( Cache )) expire after five minutes?
- Keeps labels readable when they contain a \?

Question marks inside structured substitutions, strings, or embedded code do not make the containing entry an unknown. The editor may render an escaped question mark without displaying the escape character.

When an unknown is resolved, it is rewritten as an intent statement. Its former question text and resolution history may remain available through token history and provenance storage, but they are not front-and-center language syntax.

Semantic References

The (( ... )) syntax embeds semantic references in intent groups, intents, and unknowns.

- Keeps offline work usable when (( Network )) is unavailable
- Preserves compatibility with existing configuration through (( Files.readFileSync ))
- Makes initialization failures from (( calculateThings(...) )) actionable

References use ordinary lexical visibility and name-resolution rules. An invisible, inaccessible, or nonexistent target remains representable but produces a notice.

In the token-based editor, a resolved reference retains the stable identity of its target rather than only its spelling. Renaming or moving the target updates the displayed reference as needed. Raw text without identity information is resolved again using ordinary language rules.

Typical does not have function overloads. A reference such as (( calculateThings(...) )) refers to calculateThings while deliberately omitting its argument details. Optional arguments, rest arguments, and sum types remain part of the referenced function's ordinary signature.

Semantic references create an intent reference graph. The graph supports queries in both directions:

References are followed to gather relevant evidence and perform impact analysis. A backlink does not make a remotely owned intent become owned by the referenced construct.

A semantic reference in a non-leaf fragment is inherited by every leaf below it, just as context from an intent group is inherited. A reference written in a leaf applies only to that leaf.

Incomplete code and omitted argument details inside semantic material are handled by Partial Verification.

Evaluation

Intent evaluation is a continually running background process. Work is queued and evaluated when resources are available.

The system can retrieve one intent at a time together with:

A language model can then assess whether the intent appears to be true. Evaluation results are analysis rather than compilation results. They do not determine whether the program compiles.

The tentative common audit states are:

Applications may refine or present these states differently. Their purpose is to preserve important distinctions for individual inspection, filtering, and aggregate views rather than collapse probabilistic analysis into a compiler-style pass or fail.

Assessments are observations rather than canonical truths. If repeated or independent evaluations materially disagree, the intent is inconclusive until later evaluation or a change to the intent, implementation, or evaluation context resolves the discrepancy.

An assessment becomes stale when the intent or program context known to be relevant to that assessment changes. Stale intents may then be queued for reevaluation. Exact dependency tracking and scheduling are application concerns.

Tentatively, evaluation may gather context through the intent's structural owner, group ancestry, semantic references, and program dependency graph. The language defines these relationships so that targeted retrieval is possible, but does not prescribe one fixed retrieval boundary.

Intents also participate in an implicit relationship graph. Analysis may add probabilistic conflict links between intents that appear mutually inconsistent. These links need not be visible during ordinary use; an application can surface them when a discrepancy requires attention. A conflict link identifies a contradiction to resolve without determining which intent is correct.

There is no waiver or manual-pass escape hatch for intent results. If an assessment appears wrong, the underlying cause must be addressed by clarifying or deleting the intent, correcting the implementation, improving its relationships or evaluation context, or evaluating it again.

When generated code cannot satisfy an intent, generation may continue while the discrepancy remains visible. A generator must not silently delete, weaken, or rewrite an authoritative intent to make its output appear compliant.

Evaluation state, evidence, priority, presentation, aggregation, approval state, and similar information are application-specific metadata. The language provides identity, structure, history, and reference capabilities without prescribing one universal metadata schema.

The reference graph and ownership hierarchy can narrow conflict and duplication analysis to plausible candidates. A smaller local model may continuously search those candidates. The compiler does not attempt to resolve natural-language conflicts deterministically.

Intent Granularity

Each leaf intent should express one independently evaluable statement. Shared prefixes should be factored into parent fragments when doing so reduces repetition.

- Helps customers compare unfamiliar products with confidence
- Keeps interrupted checkout work easy to resume

Intents should describe higher-level objectives whose satisfaction requires contextual judgment. Deterministic conditions belong in language mechanisms that can check them directly. For example, numeric return constraints such as “returns a positive value,” exact exclusions such as “never returns zero or NaN,” and other postconditions should use an ensure contract rather than an intent.

A language model should split compound intents during intent creation. The compiler does not currently attempt to determine whether unrestricted natural language contains multiple intents.

Evaluation state and evidence attach only to leaf intents and unknowns. Non-leaf fragments contribute text and semantic context but do not receive results such as supported, contradicted, inconclusive, unevaluated, or stale. A UI may display an aggregate summary beside a parent fragment, but that summary is a projection of descendant results rather than an assessment of the fragment itself.

Typical may eventually adopt elements of controlled natural language. Terms such as must, must not, or depends on could acquire deterministic, context-specific semantics. The extent of controlled natural language, and its effect on intent decomposition and code generation, remains unresolved.

Provenance And History

Language models may create, rewrite, move, and delete bullet fragments and intent groups. These nodes retain stable identities through token-based editing so applications can associate analysis and history with the same leaf intent or unknown across program changes.

An application may retain earlier assessments to show how an intent's status changed alongside the program. This history is enabled by intent identity but is not required by the language.

The system may retain the original speech transcript or written conversation from which an intent was extracted, together with authorship, time, interaction identity, and other provenance metadata. This information belongs to the underlying identity and history system rather than the visible language syntax.

Application-specific information should be represented by application-defined types where practical. The intent feature must not impose a built-in priority enum or another fixed application metadata shape.

Relationship To Other Features

Unresolved Questions