# Prompt: ir-reference/structure.md

See [_common.md](_common.md) for the universal rules and the
**IR-reference family contract**.

## Target

Produce `docs/generated/design/ir-reference/structure.md` — the
per-opcode reference for structural opcodes: the module, functions
and generics, struct/interface/witness-table types, and other
container-shaped opcodes that own children.

The relevant Lua ranges are `GlobalValueWithCode` (around line 786),
`module` (around line 826), `key` / `StructKey` and the witness-table
entries clustered with it. `StructType` and `InterfaceType` themselves
live in the `Type` family but their *parent* opcode behavior is
documented here because they own children (`StructField`,
`InterfaceRequirementEntry`, `WitnessTableEntry`).

## Family-specific guidance

- Split `## Opcodes` into:
  - **Module** (`module` / `ModuleInst`).
  - **Functions and generics** (`func`, `generic`, `GlobalValueWithParams`).
  - **Global state** (`global_var`, `global_param`, `globalConstant`,
    `global_generic_param`, `global_hashed_string_literals`).
  - **Struct internals** (`StructType` *as parent*, `StructField`,
    `StructKey`, `indexedFieldKey`).
  - **Interface internals** (`InterfaceType` *as parent*,
    `interface_req_entry`, `InterfaceRequirementEntry`).
  - **Witness tables** (`witness_table`, `WitnessTableEntry`,
    `thisTypeWitness`, `TypeEqualityWitness`).
  - **Symbol aliasing** (`SymbolAlias`).
- For `StructType` and `InterfaceType`, the *type-side* row lives on
  [types.md](types.md); list them here only in their container role
  (`P` flag) and cross-link.
- The `AST origin` column for structural opcodes should cite:
  - `func` -> `FuncDecl`, `AccessorDecl`, lambda lowering.
  - `generic` -> `GenericDecl`.
  - `StructType` (container side) -> `StructDecl`.
  - `InterfaceType` -> `InterfaceDecl`.
  - `witness_table` -> generated by conformance lowering.
  - `module` -> `ModuleDecl`.

## Notable opcodes

Cover at least:

- `func` — parent flag, blocks as children, the function signature
  on the `func` instruction itself.
- `generic` — function-shaped instruction whose body computes a
  type-level value, terminated by a `Return` that yields the
  generic's result.
- `module` / `ModuleInst` — top-level container; cite that linkage,
  IR-level imports, and serialized modules all hang off it.
- `StructKey` — identity for a member that is *not* keyed by name
  at the IR level; cite that struct-field lookup goes through keys.
- `witness_table` — its operand list (`subType`, `interface`) and
  the witness entries it owns.
- `SymbolAlias` — what it is for, why it must be eliminated after
  linking.

## Forbidden content

- Function-signature lowering details — see
  [../pipeline/04-ast-to-ir.md](../pipeline/04-ast-to-ir.md).
- Generic specialization — see
  [generics-and-existentials.md](generics-and-existentials.md) and
  [../pipeline/05-ir-passes.md](../pipeline/05-ir-passes.md).

## Quality checklist (in addition to the universal one and the family contract)

- [ ] Every Lua entry in `GlobalValueWithCode`, plus `module`,
      `StructKey`, `WitnessTableEntry`, `InterfaceRequirementEntry`,
      `SymbolAlias`, and `thisTypeWitness` / `TypeEqualityWitness`
      appears in the tables.
- [ ] Hierarchy diagram shows `GlobalValueWithCode` and its children.
- [ ] Cross-link to [types.md](types.md) for `StructType` /
      `InterfaceType` type-side rows.
