Files

T

gti d21a9d1140 Add 'fiscal/' from commit '102ba84500dbd9655a0471288c3e278652593ca9'

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

2026-09-29 14:43:23 -03:00

3.2 KiB

Raw Blame History

Autonomous Fiscal Completion V1 Design

Goal

Reduce deterministic fiscal gaps across the five explicitly allowlisted local Firebird databases without calling an AI provider, answering human decisions, or treating a populated ERP field as mandatory by default.

Safety Boundary

All discovery and evidence extraction is read-only. Deterministic writes are permitted only through the existing guarded executor, only for exact allowlisted paths and proven write targets. A write requires provenance, CHANGE_REQUIRED, write_eligible=true, path/company/schema/type guards, compare-before-write, exact rowcount, post-write equality, and a no-unplanned-columns audit. If any guard fails, the result remains pending. AI flags remain AI_WRITE_ALLOWED=false and FIREBIRD_AI_WRITES=0.

Workstreams

1. Requiredness and completeness

Create a versioned requiredness matrix for the 23 existing fiscal contracts. Rules are keyed by company regime/UF and product/operation facts, and produce one of REQUIRED, CONDITIONAL, OPTIONAL_REFERENCE, NOT_APPLICABLE, or ERP_NOT_USED. Implement FiscalCompletenessEvaluator to return a status per field and aggregate product metrics without requiring empty NOT_APPLICABLE fields to be filled.

2. Inbound evidence

Perform schema discovery across all five databases without assuming table names. Identify headers, items, suppliers, keys, XML/BLOB/text evidence, and relationships. Produce a sanitized evidence map and read-only analysis counts. Supplier observations remain observational until conservative deterministic rules prove they are reusable.

3. Deterministic resolution

Build provenance-aware evidence aggregation for origin, product role, ST/CEST, and dynamic CFOP entry scope. Use supplier/document agreement metrics rather than majority alone. Keep conflicts, missing evidence, company/group/product questions, and ST_WITHHELD uncertainty pending. Reuse only compatible global KB facts; tenant-specific policy fields are never copied cross-tenant.

Run dry-run and completeness metrics for all five databases. Execute only eligible deterministic writes, then reprocess and require zero second-pass writes. Preserve all current NCM conflicts.

4. Providers and AI controls

Document external product-data provider candidates without purchasing or querying them. Add an abstract provider contract and permanent-cache schema for GTIN/provider/version/hash/normalized data. Add persistent central AI usage ledger and atomic pre-call limits for run, daily, monthly, requests, and new products. Prove idempotent cache behavior with offline tests; no provider or AI network call is made.

Artifacts

The implementation must produce the requiredness matrix, inbound evidence map, provider evaluation, consolidated JSON/Markdown autonomy reports, and updated AI_PROJECT_STATE.md. Artifacts must report measured values and explicit unknowns rather than inferred fiscal answers.

Verification

Each workstream adds focused tests. The final gate runs the complete tests and central/tests suites, git diff --check, read-only invariant checks, dry-run and second-pass metrics, and confirms no external AI calls, no non-allowlisted database access, and no semantic Firebird writes.

3.2 KiB Raw Blame History