Single-File Top-Down Ordering

Reorder blocks inside one file to make the public surface readable first, then unfold supporting details.

Response Contract

• •Deliverable: return the revised file contents with blocks reordered only.
• •Chat output: no additional output beyond the deliverable.

Ordering Model

Block Scope

A block is a structural declaration unit, such as a public or exported declaration, class, function or method, and relevant type declarations.

Dependency-After

Dependency-after is a readability ordering: when one block depends on another block in the same file, place the depended-on block later so supporting definitions appear after the behavior that uses them.

Standards

Apply these standards throughout the edit. Each standard is single-sourced here and referenced elsewhere by its ID.

• •

  safety.semantics_preserve — Preserve semantics Reorder only when language semantics remain correct.

• •

  ordering.public_first — Public surface first Place public-facing blocks earlier in the file.

• •

  ordering.dependency_after — Dependency-after For same-file blocks: if A depends on B, place A before B when a valid order exists.

• •

  cycles.group — Cycles as a group If blocks form a dependency cycle, treat the cycle as a single group for placement.

Workflow

1. •

   Move public-facing blocks earlier. Apply ordering.public_first.

2. •

   Order public-facing blocks:

   • •If one depends on another, place the dependent earlier. Apply ordering.dependency_after.
   • •Otherwise keep original relative order.
3. •

   Layer supporting blocks until no new blocks are found:

   • •

     Scan the current layer in order and collect same-file block dependencies in this order:

     1. •signature and type-position references
     2. •implementation and body references
   • •

     Exclude blocks already placed and anything out of scope.

   • •

     The newly discovered blocks form the next layer in first-encounter order across the scan.

   • •

     If the next layer contains cycles, treat each cycle as a group and keep original relative order within the group. Apply cycles.group.

   • •

     Append the next layer after the current layer and repeat.

4. •

   Validate safety and revert any move that would violate semantics. Apply safety.semantics_preserve.

Acceptance Criteria

A revision is complete only if all checks pass.

• •Response: Output satisfies the Response Contract.
• •Standards satisfied: safety.semantics_preserve, ordering.public_first, ordering.dependency_after, cycles.group.