docs(formal): add table ordering convention, fix project_name key and change_history arg

Apply table ordering guidance to all formal document headers. Sort
scannable reference tables (definitions, constraints, packages)
alphabetically by first column. Fix project-name -> project_name
key and add missing change_history arg to formal_doc.with() where
needed. All documents compile cleanly against current core.typ.

Author: abitofhelp

docs/formal/software_design_specification.typ

@@ -8,6 +8,12 @@
 // Modification Policy:
 //   - Edit this file for project-specific SDS content.
 //   - Keep shared presentation logic in core.typ.
+// Table Ordering:
+//   Sort any table whose rows a reader might scan to locate a specific
+//   entry — definitions, acronyms, constraints, packages, interfaces,
+//   and similar reference tables.  Sort alphabetically by the first
+//   column.  Tables with an inherent sequence (requirement IDs within
+//   a section, change history, workflow steps) retain their logical order.
 // SPDX-License-Identifier: BSD-3-Clause
 // ============================================================================
 
@@ -100,19 +106,20 @@ This document covers:
 
 == Dependency Rules
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr, auto),
   table.header([*Package*], [*Dependencies*], [*SPARK_Mode*]),
   [Functional], [None], [On],
-  [Functional.Result], [Functional], [On],
-  [Functional.Option], [Functional], [On],
   [Functional.Either], [Functional], [On],
+  [Functional.Option], [Functional], [On],
+  [Functional.Result], [Functional], [On],
+  [Functional.Scoped], [Ada.Finalization], [Off],
   [Functional.Try], [Ada.Exceptions, Result, Option], [Off],
   [Functional.Try.Map_To_Result], [Try], [Off],
   [Functional.Try.Map_To_Result_With_Param], [Try], [Off],
-  [Functional.Try.To_Result], [Try, Result], [Off],
   [Functional.Try.To_Option], [Try, Option], [Off],
-  [Functional.Scoped], [Ada.Finalization], [Off],
+  [Functional.Try.To_Result], [Try, Result], [Off],
   [Functional.Version], [None], [On],
 )
 
@@ -145,19 +152,20 @@ src/
 
 == Package Descriptions
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr, auto),
   table.header([*Package*], [*Purpose*], [*SPARK*]),
   [`Functional`], [Root namespace, common declarations.], [On],
-  [`Functional.Result`], [Success/failure discriminated union with combinators.], [On],
-  [`Functional.Option`], [Presence/absence discriminated union with combinators.], [On],
   [`Functional.Either`], [Left/right discriminated union with combinators.], [On],
+  [`Functional.Option`], [Presence/absence discriminated union with combinators.], [On],
+  [`Functional.Result`], [Success/failure discriminated union with combinators.], [On],
+  [`Functional.Scoped`], [RAII guard generics.], [Off],
   [`Functional.Try`], [Exception-to-Result/Option bridge infrastructure.], [Off],
   [`Functional.Try.Map_To_Result`], [Declarative exception mapping (no extra parameter).], [Off],
   [`Functional.Try.Map_To_Result_With_Param`], [Declarative exception mapping (parameterized action).], [Off],
-  [`Functional.Try.To_Result`], [Procedural exception mapping (legacy).], [Off],
   [`Functional.Try.To_Option`], [Exception-to-Option for probe operations.], [Off],
-  [`Functional.Scoped`], [RAII guard generics.], [Off],
+  [`Functional.Try.To_Result`], [Procedural exception mapping (legacy).], [Off],
   [`Functional.Version`], [Library version constants.], [On],
 )
 
@@ -299,14 +307,15 @@ Consumers of the Functional library use Result and Option types for all expected
 
 == Module Responsibilities
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr),
   table.header([*Module*], [*Error Handling Role*]),
-  [Result], [Carry success/failure values through combinators.],
-  [Option], [Carry present/absent values through combinators.],
   [Either], [Carry left/right values through combinators.],
-  [Try], [Catch exceptions at boundaries and convert to Result or Option.],
+  [Option], [Carry present/absent values through combinators.],
+  [Result], [Carry success/failure values through combinators.],
   [Scoped], [Suppress exceptions from cleanup actions to prevent double-exception scenarios.],
+  [Try], [Catch exceptions at boundaries and convert to Result or Option.],
 )
 
 == Try Usage Guidelines
@@ -377,14 +386,15 @@ Functional targets a *spark-targeted* assurance posture. Core types (Result, Opt
 
 == Module Assessment
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, auto, 1fr),
   table.header([*Module*], [*SPARK*], [*Notes*]),
-  [Result], [On], [Pure functional type, fully provable.],
-  [Option], [On], [Pure functional type, fully provable.],
   [Either], [On], [Pure functional type, fully provable.],
-  [Try], [Off], [Exception handling is inherently outside SPARK.],
+  [Option], [On], [Pure functional type, fully provable.],
+  [Result], [On], [Pure functional type, fully provable.],
   [Scoped], [Off], [Ada.Finalization is outside SPARK.],
+  [Try], [Off], [Exception handling is inherently outside SPARK.],
   [Version], [On], [Constants only.],
 )
 

docs/formal/software_requirements_specification.typ

@@ -8,6 +8,12 @@
 // Modification Policy:
 //   - Edit this file for project-specific SRS content.
 //   - Keep shared presentation logic in core.typ.
+// Table Ordering:
+//   Sort any table whose rows a reader might scan to locate a specific
+//   entry — definitions, acronyms, constraints, packages, interfaces,
+//   and similar reference tables.  Sort alphabetically by the first
+//   column.  Tables with an inherent sequence (requirement IDs within
+//   a section, change history, workflow steps) retain their logical order.
 // SPDX-License-Identifier: BSD-3-Clause
 // ============================================================================
 
@@ -79,18 +85,19 @@ This Software Requirements Specification (SRS) defines the functional and non-fu
 
 == Definitions and Acronyms
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr),
   table.header([*Term*], [*Definition*]),
-  [Result], [A discriminated union representing success (Ok) or failure (Error).],
-  [Option], [A discriminated union representing presence (Some) or absence (None).],
+  [Discriminated Union], [Ada record type with a discriminant controlling the variant.],
   [Either], [A discriminated union representing one of two valid values (Left or Right).],
-  [Railway-Oriented Programming], [A pattern where operations are chained, with errors automatically propagating through the pipeline.],
+  [Functor], [Abstraction for transforming wrapped values (Map).],
+  [Monad], [Abstraction for sequencing computations (Map, And_Then).],
+  [Option], [A discriminated union representing presence (Some) or absence (None).],
   [RAII], [Resource Acquisition Is Initialization — automatic cleanup pattern using Ada finalization.],
+  [Railway-Oriented Programming], [A pattern where operations are chained, with errors automatically propagating through the pipeline.],
+  [Result], [A discriminated union representing success (Ok) or failure (Error).],
   [SPARK], [A formally verifiable subset of Ada.],
-  [Discriminated Union], [Ada record type with a discriminant controlling the variant.],
-  [Monad], [Abstraction for sequencing computations (Map, And_Then).],
-  [Functor], [Abstraction for transforming wrapped values (Map).],
 )
 
 == References
@@ -134,12 +141,13 @@ Unlike the typical hybrid DDD/Clean/Hexagonal project, Functional does not have
 
 == User Classes
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr),
   table.header([*User Class*], [*Description*]),
-  [Library Consumers], [Ada developers using Functional types in their projects.],
   [Domain Developers], [Developers implementing business logic with Result/Option.],
   [Infrastructure Developers], [Developers implementing I/O boundaries with Try bridges.],
+  [Library Consumers], [Ada developers using Functional types in their projects.],
 )
 
 == Operating Environment
@@ -158,13 +166,14 @@ Unlike the typical hybrid DDD/Clean/Hexagonal project, Functional does not have
 
 == Constraints
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr),
   table.header([*Constraint*], [*Rationale*]),
   [Ada 2022], [Required for modern language features.],
   [No Heap Allocation], [Stack-based discriminated unions ensure embedded safety.],
-  [SPARK Subset], [Core types must remain formally verifiable.],
   [No Runtime Dependencies], [Only the Ada standard library is permitted.],
+  [SPARK Subset], [Core types must remain formally verifiable.],
 )
 
 = Interface Requirements
@@ -423,13 +432,14 @@ No specific hardware requirements. The library operates within standard Ada runt
 
 == Verification Methods
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, 1fr),
   table.header([*Method*], [*Description*]),
-  [Unit Testing], [All public operations of Result, Option, Either, Try, Scoped.],
-  [SPARK Proof], [Result, Option, Either core operations.],
-  [Integration Testing], [Try with real exception scenarios.],
   [Code Review], [All changes reviewed before merge.],
+  [Integration Testing], [Try with real exception scenarios.],
+  [SPARK Proof], [Result, Option, Either core operations.],
+  [Unit Testing], [All public operations of Result, Option, Either, Try, Scoped.],
 )
 
 == Traceability Matrix

docs/formal/software_test_guide.typ

@@ -8,6 +8,12 @@
 // Modification Policy:
 //   - Edit this file for project-specific STG content.
 //   - Keep shared presentation logic in core.typ.
+// Table Ordering:
+//   Sort any table whose rows a reader might scan to locate a specific
+//   entry — definitions, acronyms, constraints, packages, interfaces,
+//   and similar reference tables.  Sort alphabetically by the first
+//   column.  Tables with an inherent sequence (requirement IDs within
+//   a section, change history, workflow steps) retain their logical order.
 // SPDX-License-Identifier: BSD-3-Clause
 // ============================================================================
 
@@ -134,13 +140,14 @@ test/
 
 == Naming Conventions
 
+// Sort rows alphabetically by the first column.
 #table(
   columns: (auto, auto, 1fr),
   table.header([*Element*], [*Convention*], [*Example*]),
+  [Runner], [`unit_runner.adb`], [`unit_runner.adb`],
   [Test file], [`test_<module>.adb`], [`test_result.adb`],
-  [Test procedure], [`Test_<Operation>_<Scenario>`], [`Test_Map_Success`],
   [Test package], [`Test_<Module>`], [`Test_Result`],
-  [Runner], [`unit_runner.adb`], [`unit_runner.adb`],
+  [Test procedure], [`Test_<Operation>_<Scenario>`], [`Test_Map_Success`],
 )
 
 == Build/Test Projects