Editing Non-Functional Requirements

<span id="non-functional-requirements"></span>
= Non-Functional Requirements =

{|
!width="23%"| Field
!width="76%"| Value
|-
| Document ID
| PGCBL-NFR-001
|-
| Document Type
| Non-Functional Requirements
|-
| System
| pgcobol — Prime Numbers Application v1.0
|-
| Version
| 1.0
|-
| Status
| Draft — performance and security targets require stakeholder input
|-
| Owner
| Lead Developer / Architect
|-
| Author
| [reverse-engineered; targets are best-practice defaults where not specified in source]
|-
| Created
| 2026-03-17
|-
| Last modified
| 2026-03-17
|-
| Classification
| Internal
|-
| Parent document
| PGCBL-BRD-001
|}

<span id="version-history"></span>
== Version History ==

{|
!width="16%"| Version
!width="22%"| Date
!width="15%"| Author
!width="15%"| Status
!width="30%"| Change Summary
|-
| 0.1
| 2026-03-17
| —
| Draft
| Initial draft from source analysis and best-practice defaults
|}


-----

<span id="table-of-contents"></span>
== Table of Contents ==

# [[#1-purpose-and-taxonomy|Purpose and Taxonomy]]
# [[#2-performance|Performance]]
# [[#3-reliability-and-availability|Reliability and Availability]]
# [[#4-security|Security]]
# [[#5-maintainability|Maintainability]]
# [[#6-portability-and-compatibility|Portability and Compatibility]]
# [[#7-operability|Operability]]
# [[#8-auditability-and-compliance|Auditability and Compliance]]
# [[#9-recoverability|Recoverability]]
# [[#10-open-issues|Open Issues]]


-----

<span id="purpose-and-taxonomy"></span>
== 1. Purpose and Taxonomy ==

Non-functional requirements (NFRs) specify '''how well''' the system must do things, as opposed to '''what''' it must do (functional requirements). They are the quality attributes of the system.

This document uses the '''ISO/IEC 25010:2011 (SQuaRE)''' quality model as its taxonomy. Each NFR is assigned a category from that model:

{|
!width="50%"| ISO 25010 Category
!width="50%"| Subcategories
|-
| '''Performance efficiency'''
| Time behaviour, resource utilisation, capacity
|-
| '''Reliability'''
| Maturity, availability, fault tolerance, recoverability
|-
| '''Security'''
| Confidentiality, integrity, non-repudiation, accountability, authenticity
|-
| '''Maintainability'''
| Modularity, reusability, analysability, modifiability, testability
|-
| '''Portability'''
| Adaptability, installability, replaceability
|-
| '''Operability'''
| Appropriateness recognisability, learnability, user error protection
|-
| '''Compatibility'''
| Co-existence, interoperability
|}

Each NFR entry follows this format:

<pre>NFR-&lt;category&gt;-&lt;NN&gt;
  Requirement:   &lt;measurable statement of what is required&gt;
  Rationale:     &lt;why this matters&gt;
  Test approach: &lt;how it will be verified&gt;
  Priority:      Must Have | Should Have | Nice to Have
  Source:        &lt;observed in code / stakeholder input / best-practice default&gt;
  Status:        [CONFIRMED] | [UNCONFIRMED — needs stakeholder sign-off]</pre>

-----

<span id="performance"></span>
== 2. Performance ==

<span id="nfr-perf-01-generation-throughput"></span>
=== NFR-PERF-01 — Generation throughput ===

'''Requirement:''' The system should generate and insert at least 1,000 primes per second under normal operating conditions (single-user, unloaded PostgreSQL on localhost).<br />
'''Rationale:''' There are approximately 50 million primes below 10^9. Without a throughput target the system may be functionally correct but practically unusable.<br />
'''Test approach:''' Time a generation run of the first 10,000 primes; divide by elapsed seconds.<br />
'''Priority:''' Should Have<br />
'''Source:''' Best-practice default [UNCONFIRMED — no target specified in source]<br />
'''Status:''' Open — target must be agreed with the system owner.

<span id="nfr-perf-02-report-generation-time"></span>
=== NFR-PERF-02 — Report generation time ===

'''Requirement:''' A report covering up to 1 million stored primes should complete within 5 minutes.<br />
'''Rationale:''' A batch report that runs overnight is operationally acceptable; one that runs for days is not.<br />
'''Test approach:''' Seed 1,000,000 rows; time a full report run.<br />
'''Priority:''' Should Have<br />
'''Source:''' Best-practice default [UNCONFIRMED]<br />
'''Status:''' Open.

<span id="nfr-perf-03-database-query-response"></span>
=== NFR-PERF-03 — Database query response ===

'''Requirement:''' The <code>SELECT prime WHERE ident = :n</code> divider lookup should return in under 50 ms at any point in the generation run.<br />
'''Rationale:''' This query is called once per trial division step; if it is slow, the entire sieve is slow.<br />
'''Test approach:''' Run EXPLAIN ANALYZE on the query with a populated table; check absence of sequential scan on <code>primes.primes</code>.<br />
'''Priority:''' Must Have<br />
'''Source:''' Algorithm design analysis<br />
'''Status:''' Open — no index on <code>ident</code> is defined in <code>primes_schema.sql</code>; a sequential scan is likely. This is a defect.


-----

<span id="reliability-and-availability"></span>
== 3. Reliability and Availability ==

<span id="nfr-rel-01-batch-completion"></span>
=== NFR-REL-01 — Batch completion ===

'''Requirement:''' A generation or report run, once started on a healthy system, should complete without manual intervention.<br />
'''Rationale:''' Batch jobs that require operator interaction to proceed are unreliable.<br />
'''Test approach:''' Run end-to-end generation and report on a healthy environment; observe for any interactive prompts or hangs.<br />
'''Priority:''' Must Have<br />
'''Source:''' Standard batch computing requirement<br />
'''Status:''' [CONFIRMED by design — no interactive prompts in the code]

<span id="nfr-rel-02-graceful-failure"></span>
=== NFR-REL-02 — Graceful failure ===

'''Requirement:''' On any database error, the system shall log a descriptive message, set an error code, and exit cleanly (closing the database connection and print file) rather than abending.<br />
'''Rationale:''' An abend may leave the database connection open or the print file in an inconsistent state.<br />
'''Test approach:''' Simulate a database failure mid-run (e.g. kill the PostgreSQL process); verify clean exit and closed resources.<br />
'''Priority:''' Must Have<br />
'''Source:''' Observed in source; partial — cleanup paragraphs exist but error propagation is incomplete (see PGCBL-IOB-001 D-RPT-01).<br />
'''Status:''' Partially met; D-RPT-01 is an open defect.

<span id="nfr-rel-03-idempotent-reset"></span>
=== NFR-REL-03 — Idempotent reset ===

'''Requirement:''' Running <code>reset-primes.sql</code> shall always produce a clean, empty, ready-to-use database state regardless of the prior state of the database.<br />
'''Rationale:''' Developers and operators must be able to reset state reliably between test runs.<br />
'''Test approach:''' Run the reset script three times consecutively; verify the same clean state each time.<br />
'''Priority:''' Must Have<br />
'''Source:''' <code>reset-primes.sql</code> uses <code>DROP … CASCADE</code> + <code>CREATE</code>; this is correct.<br />
'''Status:''' [CONFIRMED by SQL analysis]


-----

<span id="security"></span>
== 4. Security ==

<span id="nfr-sec-01-credential-storage"></span>
=== NFR-SEC-01 — Credential storage ===

'''Requirement:''' Database credentials shall not be stored in plain text within compiled program source code.<br />
'''Rationale:''' Credentials in source code are exposed to anyone who can read the binary, the source, or the version-control history.<br />
'''Test approach:''' Inspect all <code>.cbl</code> files for hard-coded user names and passwords; verify none are present.<br />
'''Priority:''' Must Have<br />
'''Source:''' OWASP Secure Coding Practice #3 — Credential Management<br />
'''Status:''' '''NOT MET''' — <code>DBUSR</code> and <code>DBPWD</code> are hard-coded in <code>primes.cbl</code> WORKING-STORAGE. Remediation: use environment variables or a secrets manager.

<span id="nfr-sec-02-principle-of-least-privilege"></span>
=== NFR-SEC-02 — Principle of least privilege ===

'''Requirement:''' The database user <code>primes_user</code> shall have only the minimum privileges required: INSERT and SELECT on <code>primes.primes</code>, USAGE on <code>primes.asc_ident</code>.<br />
'''Rationale:''' If the application account is compromised, the attacker cannot drop tables, access other schemas, or escalate.<br />
'''Test approach:''' Review PostgreSQL privilege grants; attempt a DROP TABLE as <code>primes_user</code> and verify it is denied.<br />
'''Priority:''' Must Have<br />
'''Source:''' CIS PostgreSQL Benchmark, control 6.1<br />
'''Status:''' [UNCONFIRMED — not specified in <code>primes_schema.sql</code>; only ownership is set]

<span id="nfr-sec-03-output-file-permissions"></span>
=== NFR-SEC-03 — Output file permissions ===

'''Requirement:''' <code>primes.prt</code> shall be readable only by the operator user and the intended report consumer; it shall not be world-readable.<br />
'''Rationale:''' Prime numbers are not sensitive, but the file permissions standard is a good habit and should be enforced as a baseline.<br />
'''Test approach:''' Check umask of the running process; verify <code>primes.prt</code> permissions after creation.<br />
'''Priority:''' Nice to Have<br />
'''Source:''' Best-practice default<br />
'''Status:''' [UNCONFIRMED]


-----

<span id="maintainability"></span>
== 5. Maintainability ==

<span id="nfr-main-01-three-tier-separation"></span>
=== NFR-MAIN-01 — Three-tier separation ===

'''Requirement:''' No SQL shall appear outside <code>primes.cbl</code>. No file I/O (other than console DISPLAY) shall appear outside <code>primesui.cbl</code>.<br />
'''Rationale:''' Tier separation is the principal architectural rule of this system; violating it makes changes to one tier affect others.<br />
'''Test approach:''' Grep all <code>.cbl</code> files for EXEC SQL and for SELECT/WRITE file statements; verify only the expected programs contain them.<br />
'''Priority:''' Must Have<br />
'''Source:''' Architecture design principle; observed and partially met (primesgen has an unused FD declaration — minor violation).<br />
'''Status:''' Partially met.

<span id="nfr-main-02-copybook-as-interface-contract"></span>
=== NFR-MAIN-02 — Copybook as interface contract ===

'''Requirement:''' Changes to any copybook must be reviewed for impact on all programs that COPY it before the change is applied.<br />
'''Rationale:''' Copybooks are shared; a field-size change in a copybook breaks every program that uses it without any compile-time warning in all cases.<br />
'''Test approach:''' Impact analysis process; verified by recompiling all programs after any copybook change.<br />
'''Priority:''' Must Have<br />
'''Source:''' Standard COBOL maintenance practice<br />
'''Status:''' [CONFIRMED as a process requirement — no tooling enforcement in place]

<span id="nfr-main-03-code-commentary"></span>
=== NFR-MAIN-03 — Code commentary ===

'''Requirement:''' Every paragraph shall carry a comment line stating its purpose. Every EXEC SQL block shall carry a comment stating what it does and why.<br />
'''Rationale:''' Current source has minimal commentary; future maintainers depend on the specification documents, which is insufficient.<br />
'''Test approach:''' Code review checklist.<br />
'''Priority:''' Should Have<br />
'''Source:''' COBOL coding best practice<br />
'''Status:''' '''NOT MET''' in current source.

<span id="nfr-main-04-testability"></span>
=== NFR-MAIN-04 — Testability ===

'''Requirement:''' Each tier (primesgen, primes, primesui) shall be callable in isolation with a synthetic control block, without requiring the full three-tier stack.<br />
'''Rationale:''' Unit testing individual tiers is only possible if they can be called with a test harness.<br />
'''Test approach:''' Write a minimal test driver for each program; verify it compiles and runs independently.<br />
'''Priority:''' Should Have<br />
'''Source:''' Testability principle; the method-dispatch pattern makes this achievable by design.<br />
'''Status:''' [UNCONFIRMED — no test harnesses exist]


-----

<span id="portability-and-compatibility"></span>
== 6. Portability and Compatibility ==

<span id="nfr-port-01-cobol-standard-compliance"></span>
=== NFR-PORT-01 — COBOL standard compliance ===

'''Requirement:''' Source code shall conform to COBOL 2002 (ISO 1989:2002) where GnuCOBOL extensions are not required, so that migration to a standard-compliant compiler is possible.<br />
'''Rationale:''' GnuCOBOL 4.0-early-dev is a pre-release; the team should not depend on behaviours not in the standard.<br />
'''Test approach:''' Compile with <code>-std=cobol2002</code> flag; resolve any warnings.<br />
'''Priority:''' Should Have<br />
'''Source:''' Best-practice default<br />
'''Status:''' [UNCONFIRMED — not tested]

<span id="nfr-port-02-postgresql-version-range"></span>
=== NFR-PORT-02 — PostgreSQL version range ===

'''Requirement:''' The system shall operate correctly against PostgreSQL 11 through 16.<br />
'''Rationale:''' PostgreSQL 11 is the minimum observed in the schema dump; operators may use a more recent version.<br />
'''Test approach:''' Run integration tests against PostgreSQL 11, 14, and 16.<br />
'''Priority:''' Should Have<br />
'''Source:''' Best-practice default<br />
'''Status:''' [UNCONFIRMED]


-----

<span id="operability"></span>
== 7. Operability ==

<span id="nfr-oper-01-console-log-completeness"></span>
=== NFR-OPER-01 — Console log completeness ===

'''Requirement:''' Every significant state transition (session start/stop, DB connect/disconnect, first fetch, last fetch, error) shall produce a console log entry identifying the program name, paragraph, and a human-readable message.<br />
'''Rationale:''' Operators diagnosing failures need to reconstruct what happened from the console log alone.<br />
'''Test approach:''' Run both modes; verify all defined state transitions produce a log line.<br />
'''Priority:''' Must Have<br />
'''Source:''' Observed in source; partially met — direct DISPLAY statements in <code>primes.cbl</code> bypass the structured log format.<br />
'''Status:''' Partially met.

<span id="nfr-oper-02-return-code"></span>
=== NFR-OPER-02 — Return code ===

'''Requirement:''' The process shall exit with return code 0 on success and non-zero on failure.<br />
'''Rationale:''' Job schedulers and shell scripts depend on process exit codes to detect failures.<br />
'''Test approach:''' Run with a bad argument; check <code>$?</code> in the shell.<br />
'''Priority:''' Must Have<br />
'''Source:''' POSIX convention<br />
'''Status:''' '''NOT MET''' — <code>STOP RUN</code> in GnuCOBOL returns 0 regardless of the path taken unless <code>MOVE n TO RETURN-CODE</code> is used; not present in current source.


-----

<span id="auditability-and-compliance"></span>
== 8. Auditability and Compliance ==

<span id="nfr-aud-01-run-log-retention"></span>
=== NFR-AUD-01 — Run log retention ===

'''Requirement:''' Console output from each run should be captured and retained for at least 30 days.<br />
'''Rationale:''' Enables post-hoc investigation of incorrect results or failures.<br />
'''Test approach:''' Verify a shell wrapper redirects stdout/stderr to a dated log file.<br />
'''Priority:''' Should Have<br />
'''Source:''' Best-practice default<br />
'''Status:''' [UNCONFIRMED — no wrapper script exists]

<span id="nfr-aud-02-schema-change-control"></span>
=== NFR-AUD-02 — Schema change control ===

'''Requirement:''' Changes to <code>primes_schema.sql</code> or <code>reset-primes.sql</code> must be version-controlled and reviewed before deployment.<br />
'''Rationale:''' Schema changes can destroy data or break the application silently.<br />
'''Test approach:''' Verify files are under git; verify a change-review process exists.<br />
'''Priority:''' Must Have<br />
'''Source:''' Standard DBA practice<br />
'''Status:''' [UNCONFIRMED]


-----

<span id="recoverability"></span>
== 9. Recoverability ==

<span id="nfr-rec-01-clean-restart-after-failure"></span>
=== NFR-REC-01 — Clean restart after failure ===

'''Requirement:''' After any failure, it shall be possible to restore the system to a known clean state by running <code>reset-primes.sql</code> and re-running the generation job.<br />
'''Rationale:''' Without a clean-restart procedure, a failed run leaves the database in an unknown state.<br />
'''Test approach:''' Simulate a mid-run failure; run <code>reset-primes.sql</code>; run a full generation; verify correctness.<br />
'''Priority:''' Must Have<br />
'''Source:''' <code>reset-primes.sql</code> provides this; it must be documented as the recovery procedure.<br />
'''Status:''' Script exists; recovery procedure not yet documented.

<span id="nfr-rec-02-no-partial-page-print-output"></span>
=== NFR-REC-02 — No partial-page print output ===

'''Requirement:''' The report print file shall always end with a complete, flushed page — no partial lines or missing footings.<br />
'''Rationale:''' A partial last page is confusing to report consumers.<br />
'''Test approach:''' Run a report with a number of primes that does not divide evenly by 6; inspect the last page of <code>primes.prt</code>.<br />
'''Priority:''' Must Have<br />
'''Source:''' <code>r99-stop-primesui</code> flush loop — implemented.<br />
'''Status:''' [CONFIRMED by code analysis]


-----

<span id="open-issues"></span>
== 10. Open Issues ==

{|
!width="18%"| ID
!width="18%"| Issue
!width="18%"| Owner
!width="21%"| Target
!width="21%"| Status
|-
| OI-01
| NFR-PERF-01, 02, 03 targets not confirmed by stakeholder
| System owner
| —
| Open
|-
| OI-02
| NFR-SEC-01 (hard-coded credentials) is a defect; remediation plan needed
| Lead Dev
| —
| Open
|-
| OI-03
| NFR-OPER-02 (return code) not implemented; affects job scheduler integration
| Developer
| —
| Open
|-
| OI-04
| NFR-PERF-03: no index on <code>primes.ident</code>; likely sequential scan — performance defect
| DBA
| —
| Open
|}
<hr/>
Terug naar: [[Design standards]] | [[Cobol and PostgreSQL]]