Add 'fiscal/' from commit '102ba84500dbd9655a0471288c3e278652593ca9'

git-subtree-dir: fiscal
git-subtree-mainline: d95165fc8f
git-subtree-split: 102ba84500

fiscal/docs/superpowers/specs/2026-09-16-firebird-mission-00d-design.md

@@ -0,0 +1,95 @@
+# Mission 00D: Structured Firebird Read-Only Boundary
+
+## Goal
+
+Remove arbitrary SQL from the public safety boundary, preserve legitimate
+Firebird metadata expressions internally, then connect read-only only to
+`D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB` and complete evidence-backed
+discovery when credentials and compatibility permit.
+
+## Root cause
+
+The previous `ReadOnlyConnection.execute(sql)` accepted consumer-provided SQL
+and used a blacklist/allowlist parser as its execution authority. Quoted
+identifiers could hide callable names from the textual scan, allowing potential
+procedure/UDF invocation. The same incomplete callable allowlist rejected
+legitimate Firebird expressions such as `CAST` and aggregate functions. This
+is a boundary-design failure, not a missing regex case.
+
+## Architecture
+
+- Remove `execute(sql)` and equivalent raw execution methods from the public
+  adapter consumed by collectors and mapping code.
+- Keep driver execution in a private implementation that accepts only internal
+  query identifiers and internally owned static SQL templates.
+- Expose structured catalog operations for database info, relations, columns,
+  primary/foreign keys, indexes, triggers, procedures, generators,
+  dependencies, and monitoring metadata.
+- Expose relation sampling only after relation and column identities have been
+  returned by the catalog. Validate those identities structurally, quote them
+  as Firebird identifiers, and cap the integer row limit.
+- Keep transaction-level Firebird read-only enforcement and fail closed if it
+  cannot be proven. Do not expose commit, rollback, DDL, DML, procedure
+  execution, or generator modification.
+- `collect_metadata` must require the approved structured reader at runtime,
+  not merely by type annotation.
+
+## Query ownership
+
+All metadata SQL belongs to the implementation and is selected by fixed query
+keys. Internal queries may use `CAST`, `COUNT`, `SUM`, `MIN`, `MAX`,
+`COALESCE`, joins, grouping, and other required Firebird syntax without going
+through the old arbitrary-SQL parser. Procedures and UDFs are queried only as
+metadata and never invoked.
+
+The old parser may remain as an offline diagnostic/test utility, but it has no
+authority to decide whether runtime SQL is executable. If retained, its
+documentation must clearly state that quoted identifiers and Firebird grammar
+are not security guarantees.
+
+## Sampling
+
+Sampling accepts only a relation identity previously returned by catalog
+metadata, a column set previously returned for that relation, and a validated
+small integer limit. It rejects expressions, clauses, procedures, UDFs,
+fragments, arbitrary `WHERE`/`ORDER BY`, unknown relations/columns, malformed
+quoted identifiers, and alternate database paths. It returns sanitized scalar
+evidence only; BLOB content, credentials, customer data, and unnecessary
+commercial values are excluded.
+
+## Verification gates
+
+Before any database access, tests must prove that arbitrary SQL cannot reach
+the driver, quoted identifiers cannot reintroduce callable execution,
+procedures/UDFs cannot be invoked, legitimate internal Firebird expressions are
+supported, and arbitrary adapters are rejected. Only after all focused tests
+and the full suite pass may the installed Firebird 2.5.9 client be used.
+
+The connection then targets only the authorized `.FDB`, performs a minimal
+identity query first, and uses a read-only transaction. If credentials,
+compatibility, or identity verification fail, the result remains
+`MISSION_00_BLOCKED` and no discovery query continues.
+
+## Discovery and documentation
+
+After a successful connection, collect capability-aware catalog metadata,
+identify the product relation using structural and masked sample evidence,
+correlate the ERP UI fields to database fields with `CONFIRMED`, `INFERRED`,
+or `UNKNOWN` classifications, inspect fiscal/image/incremental structures,
+and analyze trigger/procedure metadata without execution. Generate a real
+schema fingerprint only from sanitized evidence. Update the current-state
+documents and final report to describe the actual adapter, parser role,
+runtime protections, transaction behavior, connection facts, and remaining
+gaps.
+
+## Safety invariants
+
+- `AUTHORIZED_DATABASE` is the sole file opened or queried.
+- `OTHER_DATABASES_ACCESSED = 0`.
+- `APPLICATION_DDL_DML_WRITES = 0`.
+- `ERP_FILES_MODIFIED = 0`.
+- Files outside `Projeto` are read-only.
+- No credentials, raw BLOBs, full rows, or original ERP database paths enter
+  project documentation.
+- No API fiscal, image API, service, scheduler, product UPDATE, or migration
+  is implemented.