REVIEWED PUBLIC SOURCE / HISTORICAL SNAPSHOT

Bounded request grammar

This is the exact UTF-8 source text at the recorded commit. The implementation repository is private. Older records may describe earlier access, hosting or release decisions; their original wording is preserved. Links and commands inside the record remain inert source text and do not require repository access to read this record.

Original path: docs/grammar.md
Commit: e6d9e0584066ce0fb4cfb82088c1e7490a886e7b
SHA-256: 22eebf79141bca36efab694bd780dc543642dad6261ad06187e57ef70d403656
Size: 7,195 bytes

Download the exact original bytes · Read the source

# Bounded English request grammar

Renigma v0.1 proposes a reviewable plan from a small, deterministic grammar. It does not claim general language understanding, identify people, inspect files, check conditions, approve work, send email, or execute commands. An object is a label, even when it looks like a path or HTML. Unsupported text is retained in the original request and reported as unresolved.

## Supported forms

Commands use the uninflected verbs `review`, `approve`, `summarize`, `compare`, `extract`, `email`, and `delete`. Verb matching is case insensitive. Separate commands with periods, semicolons, newlines, or `then` outside quotes. `then` adds a dependency on the preceding recognized positive step; it never refers to a prohibition. A comma immediately before `then` is accepted.

```text
Alice review "draft" then Bob approve "draft".
Alice must not email "draft".
Do not delete "backup".
After I approve "draft", summarize "draft".
Alice summarize "draft" if Bob approves "draft".
Alice compare "version A" with "version B".
I extract title from "brief" so that the team can inspect the result.
Élodie review “草稿 🧭” so that work can begin.
```

- An actor is `I` or a label of one to four capitalized words, such as `Alice` or `Review Team`; letters from scripts without upper/lowercase, such as `李`, are also accepted. A colon after the actor is optional. This is syntax, not verified identity. `must`, `should`, and `will` before the verb are accepted without inferring different obligation levels.
- An omitted actor stays `null`, with an unresolved record. Actors do not carry over from previous sentences. Personal pronouns such as `you`, `we`, `he`, and `they` do not resolve to an identity. Unquoted object pronouns such as `it` remain literal and get an unresolved record.
- Single-object actions take one quoted label or a plain label of at most eight words. Straight double quotes and paired curly double quotes preserve Unicode exactly. Quoted labels may contain punctuation and grammar words. Escaped or nested quotes are outside this grammar. Plain labels permit letters, numbers, spaces, underscores, apostrophes, slashes, and hyphens; command and control words must be quoted when intended as part of a label.
- `compare X with Y` yields two objects, in that order. `extract FIELD from SOURCE` yields `[FIELD, SOURCE]`. Recipients, destinations, extraction types, and hidden file contents are not inferred.
- `do not` and `must not`, optionally following an actor, create prohibitions. Other negative forms, including `never` and `don't`, stay unresolved. A prohibition is never converted into a positive step.
- Leading `if CONDITION, COMMAND` and `after CONDITION, COMMAND`, or trailing `COMMAND if CONDITION` / `COMMAND after CONDITION`, record the complete literal condition phrase. Conditions are not evaluated or transformed into executable steps. Pronouns in a condition are flagged. Explicit `after` conditions do not become step-ID dependencies; only `then` creates those automatically.
- A final `so that OUTCOME` records a literal desired outcome. It does not establish that the outcome will happen. Grammar operators outside quotes retain their grammar meaning, including within outcome wording.

Use one explicit command per clause. Coordination with `and`/`or`, implicit negation, arbitrary paraphrases, inflected verbs, missing objects, malformed quotes, and conditional forms without the documented comma are unresolved. `If X then Y` and `If X, then Y` remain unresolved as a whole; they never detach Y from its condition. Control and negative words cannot be actor labels even when capitalized, so `Alice Should Not delete "draft"` remains unresolved rather than becoming a positive step. A nonblank request can produce only unresolved items. Blank requests and requests longer than 100,000 Python Unicode code points are rejected.

## Portable document and human corrections

The public format is `renigma.plan`, version `1`. It contains the exact `source_text`, an original `interpretation` with arrays `steps`, `prohibitions`, `outcomes`, `unresolved`, `assumptions`, and an appendable `user_corrections` array. The interpreter makes no default actor assumption, so its assumptions array is empty.

Every item has a unique `id`, `text`, and `source_spans: [{start, end}]`. Offsets are zero-based Python Unicode code points, end-exclusive, into the unmodified original request. An emoji can occupy one code point and two JavaScript UTF-16 code units; browser consumers must convert with `Array.from(source_text)`. Combining characters remain separate code points. Original item text must equal its source slice (or space-joined slices for imported multi-span evidence).

Steps and prohibitions also have `actor: string | null`, `action: string`, `objects: string[]`, `conditions: string[]`, and `after: string[]`. Outcomes and assumptions have the common fields only. Unresolved items add a `reason` string. IDs use letters, digits, underscores, and hyphens, starting with a letter. `after` references existing positive steps and cannot contain duplicates, self-references, or cycles. The array display order itself does not imply a dependency.

Each correction is exactly `{item_id, field, value}`. Editable fields are existing item fields among `actor`, `action`, `objects`, `conditions`, `after`, `text`, and `reason`. IDs, evidence spans, category membership, and the original source are not editable through this interface. Array fields require arrays of strings; actor may be null; other scalar fields require nonblank strings. Human-edited action labels may extend beyond the parser's vocabulary and remain nonexecuting data.

The last correction to the same item and field wins. Validation checks the original graph and the final corrected graph; intermediate correction history can contain a temporary cycle that a subsequent correction fixes. Correction history is not authentication or proof of authorship. The effective view is a deep copy; it never overwrites the parser interpretation or correction values. Original unresolved records remain visible as historical parser uncertainties even after a person fills a missing actor.

Strict import rejects unknown document/item/correction fields, unsupported versions, duplicate IDs, invalid shapes, evidence mismatches, and invalid dependency graphs. Each category and correction history is limited to 10,000 items, each source evidence list to 64 spans, and each objects/conditions/after list to 1,000 strings. JSON parsing and file export are caller responsibilities; these APIs accept and return plain Python data without evaluating code. JSON consumers should reject duplicate keys at their parsing boundary.

```python
interpret(text: str) -> dict
validate_document(document: dict) -> None # ValueError when invalid
effective_interpretation(document: dict) -> dict
render_text(document: dict) -> str
```

JSON export/import retains both the original interpretation and corrections. Plain-text rendering is a readable view, not a lossless replacement for the JSON document. HTML frontends must insert all source and correction values as text, never as HTML.