GTI_GERENCIADOR_FISCAL/docs/superpowers/plans/2026-09-16-firebird-mission-00e.md

Mission 00E Provenance and Real Discovery Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans (recommended). Steps use checkbox (- [ ]) syntax for tracking.

Goal: Formalize the trusted-process boundary, prove the imported fdb provenance and Firebird compatibility, then execute complete read-only discovery only against the authorized FDB.

Architecture: The existing structured reader and private operation registry remain the runtime boundary; Python same-process introspection is explicitly outside the threat model. A provenance module will inspect module origin, distribution metadata, import paths, and local shadowing before the live driver is imported or used. The final workflow will require this gate, the installed Firebird client, target identity, and complete sanitized discovery evidence.

Tech Stack: Python 3.10+, installed fdb 2.0.4, installed Firebird 2.5.9.27139 client, importlib.metadata, pytest, existing structured catalog/mapping/fingerprint modules.

Global Constraints

• TRUSTED_PROCESS = TRUE; malicious same-process introspection is outside this component boundary.
• Only D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB may be opened or queried.
• External ERP files under D:\PROJETOS\GTISISTEMAS\ outside Projeto are READ_ONLY_EXTERNAL_SYSTEM.
• APPLICATION_DDL_DML_WRITES = 0, OTHER_DATABASES_ACCESSED = 0, and ERP_FILES_MODIFIED = 0.
• No public SQL execution or registry mutation API; procedures/UDFs are metadata-only.
• No dependency update, service/configuration change, arbitrary Firebird installation, or guessed credential.
• No database access before the provenance and safety gates pass.
• Never store credentials, original ERP database paths, raw BLOBs, full rows, or unnecessary personal/commercial data.
• Git identity must not be invented or configured; report GIT_IDENTITY_NOT_CONFIGURED when absent.

---

Task 1: Formalize threat model and registry hardening

Files:

• Modify: docs/AI_PROJECT_STATE.md
• Modify: docs/MISSION_00_REPORT.md
• Modify: src/gti_discovery/firebird_queries.py
• Modify: src/gti_discovery/catalog.py
• Test: tests/test_catalog.py
• Test: tests/test_read_only_boundary.py

Interfaces:

• Preserves the structured public reader and private immutable operation registry.

• Produces no public operation-registration mutator and no raw SQL API.

• Step 1: Write failing threat-model/registry tests

Assert TRUSTED_PROCESS = TRUE is documented, package exports contain no raw execution, registry maps are immutable, no public registration function exists, and normal callers cannot mutate approved operation types. Do not test deliberate access to Python internals as a security requirement.

• Step 2: Implement minimal registry hardening

Keep operation registration module-private and centralized; use immutable mappings and exact approved reader/adapter types. Remove only accidental public aliases or mutators. Do not add cryptographic or sandbox-like mechanisms.

• Step 3: Document actual boundary

State which protections are runtime, which parser code is offline-only, and that a process already running arbitrary Python is outside scope. Remove claims that imply cryptographic isolation.

• Step 4: Run focused/full tests

Run python -m pytest tests/test_catalog.py tests/test_read_only_boundary.py -q and python -m pytest tests -q. Expected: PASS without database access.

Task 2: Prove fdb module provenance and shadowing absence

Files:

• Create: src/gti_discovery/provenance.py
• Create: tests/test_provenance.py
• Create: docs/superpowers/sdd/2026-09-16-firebird-mission-00e/task-2-report.md

Interfaces:

• Produces inspect_fdb_provenance() -> dict with module_file, module_package, module version, distribution name/version/location, interpreter, working directory, relevant sys.path/PYTHONPATH, and shadowing findings.

• Produces validate_fdb_provenance(expected_version="2.0.4") -> dict and raises a sanitized error on ambiguity/mismatch.

• Step 1: Write failing provenance tests

Test installed module metadata correlation, module file under expected site-packages, distribution/version agreement, detection of local fdb.py/fdb directory and unexpected .pth, and rejection of a shadowed/mismatched module. Use monkeypatched fixtures; never import or connect to another database.

• Step 2: Implement provenance inspection

Use importlib.util.find_spec, importlib.metadata.distribution/version, fdb.__file__, fdb.__package__, sys.executable, Path.cwd(), sys.path, and PYTHONPATH. Resolve the actual file and distribution location. Do not print credential values or scan external databases.

• Step 3: Implement local shadowing scan

Search only Projeto for exact fdb.py, fdb directory, and .pth candidates. Treat ambiguous duplicate locations as blocked. Record paths only for project-local shadowing evidence, not ERP database paths.

• Step 4: Run provenance tests and write report

Run python -m pytest tests/test_provenance.py tests/test_read_only_boundary.py -q and python -m pytest tests -q. Write sanitized provenance results and GIT_IDENTITY_NOT_CONFIGURED status to the task report.

Task 3: Pin and validate the proven dependency/client pair

Files:

• Modify: pyproject.toml
• Modify: scripts/run_firebird_discovery.py
• Create: tests/test_dependency_compatibility.py
• Create: docs/superpowers/sdd/2026-09-16-firebird-mission-00e/task-3-report.md

Interfaces:

• Produces validate_firebird_runtime() -> dict that requires the proven fdb distribution/version and installed Firebird 2.5.9 client evidence before driver use.

• Produces sanitized client path/version/architecture evidence.

• Step 1: Write failing compatibility tests

Test wrong distribution version, module/distribution mismatch, missing client, wrong client version, shadowing, unsupported read-only TPB, and valid installed fdb 2.0.4 plus Firebird 2.5.9.27139 fixtures. Tests must fail before any driver connection.

• Step 2: Record the existing dependency without unnecessary installation

Add the appropriate exact fdb 2.0.4 dependency declaration only if the project dependency mechanism requires it; do not download or update packages. Document why this version matches the installed Firebird 2.5.9 client.

• Step 3: Implement pre-import compatibility gate

Validate distribution metadata, module provenance, client DLL existence/version, architecture evidence, and exact installed read-only isolation API before importing/using fdb for connection. Fail closed on ambiguity.

• Step 4: Run tests and record evidence

Run python -m pytest tests/test_dependency_compatibility.py tests/test_provenance.py -q and python -m pytest tests -q. Do not connect to the database.

Task 4: Execute gated real discovery and finalize documentation

Files:

• Modify: scripts/run_firebird_discovery.py
• Modify: src/gti_discovery/mapping.py
• Modify: docs/AI_PROJECT_STATE.md
• Modify: docs/DATABASE_DISCOVERY.md
• Modify: docs/SCHEMA_MAPPING.md
• Modify: docs/MISSION_00_REPORT.md
• Create: docs/superpowers/sdd/2026-09-16-firebird-mission-00e/task-4-report.md

Interfaces:

• Consumes provenance/runtime validation and structured reader/sampling APIs from Tasks 1-3.

• Produces sanitized connection facts, full catalog discovery, product/UI fiscal mapping, image/incremental/trigger evidence, and a real fingerprint only when complete.

• Step 1: Run the complete pre-connection gate

Run all focused tests and python -m pytest tests -q. Confirm no public SQL API, immutable registry, provenance match, no shadowing, compatible client, and green suite. If any fails, write MISSION_00_BLOCKED and do not connect.

• Step 2: Inspect installed Firebird evidence read-only

Use services/processes/DLL/tools/configuration only as read-only evidence. Do not start/stop/restart services or modify external ERP files. Keep credentials and original database paths out of reports.

• Step 3: Connect to the sole authorized target

Require process credentials without logging them, validate the absolute allowlist path, configure Firebird transaction READ ONLY, issue the minimal identity query first, and compare returned identity. Never use another .FDB, write probe, procedure, UDF, generator, or DDL/DML.

• Step 4: Run structured discovery

Collect all available Firebird catalogs through operation keys, use catalog-issued bounded samples, and map product fields plus every UI fiscal field (NCM, CFOP/CST entrada/saída, ICMS, CEST, CSOSN, PIS/COFINS, IPI, origem, IAT, incidência, IPPT). Investigate Foto/image/BLOB subtype/relationship, incremental evidence, and trigger/procedure dependencies without execution.

• Step 5: Produce fingerprint and current documents

Generate a sanitized real fingerprint only for complete evidence and classify it. Update current-state documents with the threat model, provenance, client, connection, schema, mappings, gaps, and exact safety counters. Preserve MISSION_00_BLOCKED if any live prerequisite or discovery result is unavailable.

• Step 6: Final verification and Git status

Run python -m pytest tests -q, git diff --check, git status --short --branch, git config user.name, and git config user.email. Verify no external file changes and no other database access. Do not configure Git or commit if identity is absent.

Plan Self-Review

• The specification's threat model, registry hardening, provenance, shadowing, dependency/client validation, pre-import gate, real connection, discovery, UI mapping, image/incremental/trigger review, documentation, tests, and Git requirements are covered by Tasks 1-4.
• No database access is permitted before Task 4 Step 1 passes.
• TRUSTED_PROCESS = TRUE avoids pretending Python private objects are cryptographic isolation while retaining accidental-use defenses.
• All runtime interfaces use structured operations; the old parser cannot authorize internal SQL.
• No placeholder instructions, arbitrary sampling, dependency download, service mutation, or external file write is permitted.