docs(opy): establish audited OverPy language support documentation

README.md

@@ -96,8 +96,9 @@ compatibility corpus and pinned OverPy reference evidence.
 | Workshop → OPY reconstruction | ⏳ Not yet | Will consume canonical `workshop-rs` semantics and remain owned by `opy-rs` |
 
 Exact per-feature evidence remains available in the
-[human-readable support reference](docs/opy/support-matrix.md) and
-[machine-readable support matrix](compatibility/support-matrix.json).
+[canonical human-readable support contract](docs/language-support.md). Internal
+fixture and implementation metadata remains in
+[compatibility/support-matrix.json](compatibility/support-matrix.json).
 
 ## Relationship with Wright
 

compatibility/support-matrix.json

@@ -1,5 +1,6 @@
 {
   "schemaVersion": 1,
+  "visibility": "internal-engineering-metadata",
   "artifact": "opy-rs OverPy feature inventory and support matrix",
   "reference": {
     "name": "overpy",

docs/README.md

@@ -18,7 +18,7 @@ architecture, compatibility evidence, APIs, and internal contracts live here.
 
 ## Compatibility
 
-- [Support reference](opy/support-matrix.md): detailed, corpus-evidenced OverPy
+- [OverPy support contract](language-support.md): audited, human-readable OverPy
   feature coverage.
 - [Compatibility baseline](opy/compatibility-baseline.md): planning/reference
   inventory for remaining OverPy surface and compatibility priorities.

docs/compatibility/upstream-references.md

@@ -103,8 +103,8 @@ The harness invokes the oracle only through documented, isolated entry points:
 
 ### Upstream surfaces inspected for the inventory
 
-The feature inventory in [`docs/opy/support-matrix.md`](../opy/support-matrix.md)
-and [`docs/opy/compatibility-baseline.md`](../opy/compatibility-baseline.md) is
+The feature inventory in [`docs/language-support.md`](../language-support.md) and
+its linked component inventories is
 grounded in the pinned tree, specifically:
 
 * `README.md`: user-visible syntax tour (rules, annotations, subroutines,
@@ -259,7 +259,7 @@ when the oracle is absent.
 
 ## Related documents
 
-* [`docs/opy/support-matrix.md`](../opy/support-matrix.md): corpus-evidenced declared surface and current states
+* [`docs/language-support.md`](../language-support.md): audited public support contract and current states
 * [`docs/opy/compatibility-baseline.md`](../opy/compatibility-baseline.md): tiered planning baseline
 * [`docs/opy/compat-manifest-spec.md`](../opy/compat-manifest-spec.md): machine-readable semantic manifest specification
 * [`docs/opy/tooling-notes.md`](../opy/tooling-notes.md): harness usage

docs/language-support.md

@@ -0,0 +1,65 @@
+# OverPy support
+
+This is the canonical, human-readable compatibility contract for `opy-rs`.
+The detailed inventories linked here are part of the same contract.
+
+## Reference and audit boundary
+
+| Field | Value |
+| --- | --- |
+| OverPy package | `9.7.10` |
+| Content commit | `889d9749d1def17f146548cbddb94ea1ab015847` (`v9.7.10`) |
+| Repository | <https://github.com/Zezombye/overpy> |
+| Registry integrity | `sha512-oX17nauJcPTaKIrRFY/rD0Rl8atqFUVv9Hg2TKH+A68/fC8+ZO344Mkd1A/Y0oOVp1hr5tktMBjzMEDDnMEYUw==` |
+| Audited language | `en-US` |
+
+The inventory was audited from the pinned upstream tree, from outside the
+`opy-rs` implementation: the upstream README and public API declaration;
+`src/compiler/` grammar, preprocessing, compiler, translation and decompiler
+surfaces; `src/data/opy/` keyword, annotation, builtin, member, module, macro
+and preprocessing registries; `src/data/` Workshop domains; upstream compile,
+decompile, CLI and QuickJS tests; and the pinned executable oracle. Existing
+`opy-rs` fixtures, HIR names, support matrix entries and issue lists were used
+only to determine the second column, never to construct the audited set.
+
+## Status vocabulary
+
+Only these public states are used:
+
+- `✅ Supported` — the claimed user-visible behavior works within the notes.
+- `🚧 Coming soon` — the pinned capability is recognized, but current behavior
+  is incomplete.
+- `❌ Unsupported` — the capability is outside the current contract.
+
+“Supported” is an end-to-end claim for the stated row. Parsing a construct or
+having a name in a manifest is not enough to make a compilation row green.
+
+## Audited capability summary
+
+| Area | Status | Detailed inventory |
+| --- | --- | --- |
+| Source syntax, literals and expressions | 🚧 Coming soon | [syntax and project composition](language-support/syntax-and-projects.md) |
+| Assignments, declarations, rules and control flow | 🚧 Coming soon | [syntax and project composition](language-support/syntax-and-projects.md) |
+| Builtins, member functions, constants and contextual domains | 🚧 Coming soon | [callables and domains](language-support/callables-and-domains.md) and [complete registries](language-support/registries.md) |
+| Preprocessing, includes, modules and macros | 🚧 Coming soon | [syntax and project composition](language-support/syntax-and-projects.md) and [complete registries](language-support/registries.md) |
+| Strings, translations and custom-game settings | 🚧 Coming soon | [syntax and project composition](language-support/syntax-and-projects.md) |
+| Compiler directives, optimization and post-compile hooks | 🚧 Coming soon | [tooling and backend](language-support/tooling-and-backend.md) and [complete registries](language-support/registries.md) |
+| Standalone compiler and CLI | ✅ Supported | [tooling and backend](language-support/tooling-and-backend.md) |
+| Workshop-to-OPY decompilation | ❌ Unsupported | [tooling and backend](language-support/tooling-and-backend.md) |
+
+The summary is intentionally conservative: the audited upstream surface is
+larger than the currently evidenced `opy-rs` surface. Detailed rows make gaps
+explicit instead of hiding them in a category-level green row.
+
+## Contract maintenance
+
+`compatibility/support-matrix.json` is retained as **internal engineering
+metadata** for fixture relationships, provenance and implementation tracking.
+It is not a public inventory and its internal states are not public support
+states. `docs/opy/support-matrix.md` is retained as historical context and
+must not introduce another public status vocabulary.
+
+The next step is a separate exhaustive conformance issue driven by the audited
+leaf identities in these documents. This issue does not turn the inventory
+into a fixed feature-count assertion or silently convert known gaps into
+passing cases.

docs/language-support/callables-and-domains.md

@@ -0,0 +1,63 @@
+# OverPy audited inventory: callables and domains
+
+Source: pinned OverPy `9.7.10`, content commit
+`889d9749d1def17f146548cbddb94ea1ab015847`. The external callable registries
+are `src/data/opy/functions.ts`, `memberFunctions.ts`, `constants.ts`,
+`modules.ts`, and `macros.ts`; Workshop registries are `src/data/actions.ts`,
+`values.ts`, `constants.ts`, `heroes.ts`, `maps.ts`, `gamemodes.ts`,
+`localizedStrings.ts`, and `customGameSettings.ts`.
+
+The upstream registries are the audited inventory source and are not copied
+into `opy-rs`. Each callable contract has a spelling, receiver (if any),
+ordered arguments, argument type/domain, optional/default behavior, return
+behavior, and dispatch rule.
+
+## Standalone functions and operators
+
+| Feature / representative leaf | Status | Audited contract |
+| --- | --- | --- |
+| `abs(value)` | ✅ Supported | One numeric value; numeric result. |
+| `len(arrayOrString)` | ✅ Supported | One array/string value; integer result. |
+| `range(stop)` / `range(start, stop[, step])` | ✅ Supported | Optional start and step have distinct defaults. |
+| `wait(duration[, reevaluation])` | ✅ Supported | Reevaluation has an optional default. |
+| `raiseToPower(base, exponent)` | ✅ Supported | Two numeric arguments in order; value operation. |
+| `sorted(array[, key])` | ✅ Supported | Optional lambda key; element/index binder is contextual. |
+| `all(array)` / `any(array)` | ✅ Supported | One boolean-array value. |
+| `random.randint(min, max)` | 🚧 Coming soon | Two inclusive integer bounds; integer result. |
+| `random.uniform(min, max)` | 🚧 Coming soon | Two float bounds; float result. |
+| `random.choice(array)` | 🚧 Coming soon | One array; returns an element or supplied non-array value. |
+| `random.shuffle(array)` | 🚧 Coming soon | One array; returns a copied array. |
+| `_(contextOrString[, string])` | 🚧 Coming soon | One-argument and two-argument modes differ. |
+
+## Receiver/member functions
+
+| Feature / representative leaf | Status | Audited contract |
+| --- | --- | --- |
+| `array.append(value)` | ✅ Supported | Array receiver; mutating; arrays are extended. |
+| `array.concat(value)` | ✅ Supported | Array receiver; returns a copy. |
+| `array.filter(lambda)` | ✅ Supported | Lambda result selects elements; optional index binder. |
+| `array.map(lambda)` | ✅ Supported | Lambda result replaces each element. |
+| `array.all([lambda])` / `array.any([lambda])` | ✅ Supported | Optional lambda defaults to element truthiness. |
+| `array[index]` and `array.slice(start, count)` | ✅ Supported | Indexing and slicing have different arguments. |
+| `string.format(...)` | 🚧 Coming soon | Variadic formatting remains incomplete. |
+| `player.setStatusEffect(player, assister, status, duration)` | 🚧 Coming soon | Receiver plus four ordered explicit arguments. |
+| `vector.x`, `.y`, `.z` | ✅ Supported | Property-like vector access; numeric result. |
+| `self` in member macros | 🚧 Coming soon | Dispatch target is the macro receiver. |
+
+## Constants, enums and contextual dispatch
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| `Hero`, `Map`, `Gamemode`, `Team`, `Slot`, `Color`, `Button` domains | 🚧 Coming soon | Membership and spelling are domain-specific. |
+| `Vector.UP/DOWN/LEFT/RIGHT/FORWARD/BACKWARD` | ✅ Supported | Constants are separate from arbitrary vectors. |
+| `Math.PI`, `Math.E`, `Math.INFINITY`, `Math.EPSILON` | 🚧 Coming soon | Numeric constants are distinct leaves. |
+| User enum assignment and inferred increments | ✅ Supported | Separate from Workshop catalog domains. |
+| Contextual `None`/reevaluation enum dispatch | 🚧 Coming soon | `ChaseTimeReeval`, `ChaseRateReeval` and `Invis` differ. |
+| Alias resolution (`getCurrentHero`, `hasStatusEffect`, `ChaseReeval`) | ✅ Supported | Non-contextual and call-context aliases differ. |
+
+The pinned `functions.ts`, `actions.ts`, `memberFunctions.ts` and `values.ts`
+registries contain the complete callable surface. The audit keeps families
+separate because action/value position, receiver type, defaults, overloads and
+return behavior differ. A name in the current internal manifest is evidence
+for `opy-rs` only; it does not expand this inventory or make an incomplete
+callable green.

docs/language-support/registries.md

@@ -0,0 +1,193 @@
+# OverPy audited inventory: complete source registries
+
+This page is the leaf inventory for the named upstream registries. Every key
+in the pinned OverPy `9.7.10` files is listed below; no current `opy-rs`
+manifest or fixture is used to define the set. The upstream registry supplies
+the full argument order, argument type/domain, defaults, return behavior and
+dispatch rule. The user-facing status is reconciled against current
+`opy-rs` evidence.
+
+Reference: `889d9749d1def17f146548cbddb94ea1ab015847`.
+
+## Keywords (`src/data/opy/keywords.ts`)
+
+| Upstream key | Status |
+| --- | --- |
+| `and` | ✅ Supported |
+| `or` | ✅ Supported |
+| `not` | ✅ Supported |
+| `bool` | ✅ Supported |
+| `float` | ✅ Supported |
+| `int` | ✅ Supported |
+| `signed` | ✅ Supported |
+| `unsigned` | ✅ Supported |
+| `case` | ✅ Supported |
+| `default` | ✅ Supported |
+| `switch` | ✅ Supported |
+| `def` | ✅ Supported |
+| `subroutine` | ✅ Supported |
+| `rule` | ✅ Supported |
+| `del` | 🚧 Coming soon |
+| `elif` | ✅ Supported |
+| `else` | ✅ Supported |
+| `if` | ✅ Supported |
+| `enum` | ✅ Supported |
+| `for` | ✅ Supported |
+| `while` | ✅ Supported |
+| `globalvar` | ✅ Supported |
+| `playervar` | ✅ Supported |
+| `goto` | 🚧 Coming soon |
+| `loc` | 🚧 Coming soon |
+| `in` | ✅ Supported |
+| `lambda` | ✅ Supported |
+| `macro` | ✅ Supported |
+| `self` | 🚧 Coming soon |
+| `settings` | 🚧 Coming soon |
+| `main` | 🚧 Coming soon |
+| `gamemodes` | 🚧 Coming soon |
+| `heroes` | 🚧 Coming soon |
+
+## Preprocessing directives (`src/data/opy/preprocessing.ts`)
+
+| Upstream key | Status |
+| --- | --- |
+| `allowMacroRedeclaration` | 🚧 Coming soon |
+| `define` | ✅ Supported |
+| `debugElementCount` | 🚧 Coming soon |
+| `disableInspector` | 🚧 Coming soon |
+| `suppressWarnings` | 🚧 Coming soon |
+| `mainFile` | ✅ Supported |
+| `include` | ✅ Supported |
+| `excludeVariablesInCompilation` | 🚧 Coming soon |
+| `setupTags` | 🚧 Coming soon |
+| `disableOptimizations` | 🚧 Coming soon |
+| `enableOptimizations` | 🚧 Coming soon |
+| `optimizeForSize` | 🚧 Coming soon |
+| `optimizeForSizeAggressive` | 🚧 Coming soon |
+| `disableOptimizeForSize` | 🚧 Coming soon |
+| `optimizeStrict` | 🚧 Coming soon |
+| `disableOptimizeStrict` | 🚧 Coming soon |
+| `replace0ByCapturePercentage` | 🚧 Coming soon |
+| `replace0ByPayloadProgressPercentage` | 🚧 Coming soon |
+| `replace0ByIsMatchComplete` | 🚧 Coming soon |
+| `replace1ByMatchRound` | 🚧 Coming soon |
+| `replaceTeam1ByControlScoringTeam` | 🚧 Coming soon |
+| `replaceEmptyStringByEmptyArray` | 🚧 Coming soon |
+| `replaceEmptyStringByVariable` | 🚧 Coming soon |
+| `translations` | 🚧 Coming soon |
+| `translateWithPlayerVar` | 🚧 Coming soon |
+| `useVariableForCompressionAlphabet` | 🚧 Coming soon |
+| `extension` | 🚧 Coming soon |
+| `globalvarInitRuleName` | 🚧 Coming soon |
+| `playervarInitRuleName` | 🚧 Coming soon |
+| `keepUnusedTranslations` | 🚧 Coming soon |
+| `disableTranslationSourceLines` | 🚧 Coming soon |
+| `writeToOutputFile` | 🚧 Coming soon |
+| `postCompileHook` | 🚧 Coming soon |
+| `rulePrefix`, `rulePrefixTemplate` | 🚧 Coming soon |
+
+## Annotations (`src/data/opy/annotations.ts`)
+
+| Upstream key | Status | Contract |
+| --- | --- | --- |
+| `@Name` | ✅ Supported | One string literal; subroutine rule name. |
+| `@Event` | ✅ Supported | One event-domain value. |
+| `@Team` | ✅ Supported | One team-domain value. |
+| `@Slot` | ✅ Supported | One slot-domain value; mutually exclusive with `@Hero`. |
+| `@Hero` | ✅ Supported | One hero-domain value; mutually exclusive with `@Slot`. |
+| `@Condition` | ✅ Supported | One condition expression; repeatable. |
+| `@SuppressWarnings` | ✅ Supported | Space-separated warning names. |
+| `@Disabled` | ✅ Supported | No arguments; disables generated rule. |
+| `@Delimiter` | ✅ Supported | No arguments; preserves a UI delimiter rule. |
+| `@NewPage` | ✅ Supported | No required arguments; inserts page boundary rules. |
+
+## Modules (`src/data/opy/modules.ts`)
+
+| Upstream key | Status | Contract |
+| --- | --- | --- |
+| `random.randint(min, max)` | 🚧 Coming soon | Two inclusive integer bounds; integer result. |
+| `random.uniform(min, max)` | 🚧 Coming soon | Two float bounds; float result. |
+| `random.choice(array)` | 🚧 Coming soon | One array; element result. |
+| `random.shuffle(array)` | 🚧 Coming soon | One array; copied array result. |
+
+## Built-in macros (`src/data/opy/macros.ts`)
+
+| Upstream key | Status |
+| --- | --- |
+| `buttonToString` | 🚧 Coming soon |
+| `.getEffectiveHero`, `.getOppositeTeam` | 🚧 Coming soon |
+| `getRealClosestPlayer`, `getRealClosestPlayers` | 🚧 Coming soon |
+| `getRealFarthestPlayer`, `getRealFarthestPlayers` | 🚧 Coming soon |
+| `.getRealPlayerClosestToReticle`, `.getRealPlayersClosestToReticle` | 🚧 Coming soon |
+| `getRealPlayersInRadius`, `.getRealPlayersInViewAngle` | 🚧 Coming soon |
+| `getSign`, `getAllPlayers` | 🚧 Coming soon |
+| `hudHeader`, `hudSubheader`, `hudSubtext` | 🚧 Coming soon |
+| `lerp`, `lineIntersectsSphere` | 🚧 Coming soon |
+| `print`, `.reverse`, `timeToString`, `.unique` | 🚧 Coming soon |
+
+## Built-in functions and member functions
+
+The following table lists every key in `src/data/opy/functions.ts`; entries
+beginning with `.` are receiver dispatch entries. The separate
+`src/data/opy/memberFunctions.ts` property entries follow it.
+
+| Upstream key | Status |
+| --- | --- |
+| `_`, `__`, `___` | 🚧 Coming soon |
+| `all` | ✅ Supported |
+| `any` | ✅ Supported |
+| `.append` | ✅ Supported |
+| `.all` | ✅ Supported |
+| `.any` | ✅ Supported |
+| `.filter` | ✅ Supported |
+| `.map` | ✅ Supported |
+| `arrayToString` | 🚧 Coming soon |
+| `ceil` | 🚧 Coming soon |
+| `floor` | 🚧 Coming soon |
+| `round` | 🚧 Coming soon |
+| `hsl` | 🚧 Coming soon |
+| `chaseAtRate` | 🚧 Coming soon |
+| `chaseOverTime` | 🚧 Coming soon |
+| `compress` | 🚧 Coming soon |
+| `compressed` | 🚧 Coming soon |
+| `decompressNumbers` | 🚧 Coming soon |
+| `decompressVectors` | 🚧 Coming soon |
+| `createCasedProgressBarIwt` | 🚧 Coming soon |
+| `debug` | 🚧 Coming soon |
+| `.format` | 🚧 Coming soon |
+| `.remove` | 🚧 Coming soon |
+| `getCurrentMap` | ✅ Supported |
+| `.getNormal` | 🚧 Coming soon |
+| `.getPlayerHit` | 🚧 Coming soon |
+| `.getHitPosition` | 🚧 Coming soon |
+| `log` | 🚧 Coming soon |
+| `pass` | ✅ Supported |
+| `range` | ✅ Supported |
+| `raycast` | 🚧 Coming soon |
+| `ruleCondition` | ✅ Supported |
+| `sorted` | ✅ Supported |
+| `spacesForString` | 🚧 Coming soon |
+| `spacesForLength` | 🚧 Coming soon |
+| `strVisualLength` | 🚧 Coming soon |
+| `splitDictArray` | 🚧 Coming soon |
+| `stopChasing` | 🚧 Coming soon |
+| `tabular` | 🚧 Coming soon |
+| `.toArray` | 🚧 Coming soon |
+| `x` (property member) | ✅ Supported |
+| `y` (property member) | ✅ Supported |
+| `z` (property member) | ✅ Supported |
+
+The upstream Workshop action/value registries are separate complete data
+surfaces in `src/data/actions.ts` and `src/data/values.ts`. They are canonical
+Workshop semantics owned by `workshop-rs`; this document does not copy those
+registries into `opy-rs`. Their OPY spellings and dispatch contracts are
+tracked by the function/member rows above and by the owning Workshop
+catalogue.
+
+## Constants (`src/data/opy/constants.ts`)
+
+| Upstream key | Status |
+| --- | --- |
+| `Vector` (`UP`, `DOWN`, `LEFT`, `RIGHT`, `FORWARD`, `BACKWARD`) | ✅ Supported |
+| `Math` (`PI`, `E`, `INFINITY`, `EPSILON`, and documented spacing/radius constants) | 🚧 Coming soon |
+| `Texture` (complete texture constant registry) | 🚧 Coming soon |