# Bilancio intelligente Vera specialist module for making the existing preparation of individual Italian OIC annual accounts intelligent. Vera participates across source understanding, mapping, ambiguity recognition, missing-information requests, prior-year reuse, schedule and note preparation, inconsistency resolution, and professional review. Exact arithmetic, statutory rules, reconciliations, and XBRL rendering remain deterministic and auditable. Model participation uses the same bounded packet contract in Codex and Cowork. Mapping is limited to fifty selected accounts; disclosure activation starts with twenty accounts and supports exact selectors; narrative drafting uses the section's rule-linked accepted evidence plus optional exact selectors; workflow, question, prior-year, and issue packets have fixed page bounds. Every packet carries a context hash and disclosed/available counts, while paginated or selector-based follow-ups keep the complete case reachable without sending `case.json` or the full source population by default. `bilancio-xbrl-it` is the stable internal technical identifier. XBRL is one export adapter for the approved canonical bilancio; it is not the product identity or the intelligence layer. See the skill references for the fixed product thesis and current implementation evidence. ## Controlled service configuration The MCP bridge fails closed unless the host provides authenticated tenant, actor, role, and storage settings. Imports and returned external reports are read only below `VERA_XBRL_INPUT_ROOT`; the model cannot choose an arbitrary host path. The official taxonomy inputs are deployment configuration rather than request fields: - `VERA_XBRL_STORAGE_ROOT` - `VERA_XBRL_INPUT_ROOT` - `VERA_XBRL_TENANT_ID` - `VERA_XBRL_ACTOR_ID` - `VERA_XBRL_ROLES` - `VERA_XBRL_TAXONOMY_CATALOGUE` - `VERA_XBRL_TAXONOMY_PACKAGE` - `VERA_XBRL_TAXONOMY_REGISTRY` - `VERA_XBRL_STATUTORY_RULE_PACK` (optional host override; the bundled effective-dated form pack is the default) - `VERA_XBRL_DISCLOSURE_RULE_PACK` (optional host override; the bundled effective-dated disclosure pack is the default) - `VERA_XBRL_STATUTORY_PRESENTATION_RULE_PACK` (optional host override; the bundled versioned pack is the default) - `VERA_XBRL_SCHEDULE_TAXONOMY_RULE_PACK` (optional host override; the bundled effective-dated note-table adapter pack is the default) - `VERA_XBRL_SCANNER_COMMAND_JSON` - `VERA_XBRL_SCANNER_ENGINE` - `VERA_XBRL_SCANNER_SIGNATURE_VERSION` - `VERA_XBRL_ARTIFACT_SIGNING_SECRET` - `VERA_XBRL_ARTIFACT_DOWNLOAD_BASE_URL` - `VERA_XBRL_RETENTION_DAYS` - `VERA_XBRL_INTELLIGENCE_COMMAND_JSON` - `VERA_XBRL_INTELLIGENCE_TIMEOUT_SECONDS` The configured catalogue and package are required for the pre-approval local XBRL review. The catalogue alone is required for export. TEBENI remains a separate, user-controlled external check. Conversational and background-worker file ingestion requires a host scanner command encoded as a JSON argument array. Vera appends the controlled absolute file path as one argument, never invokes a shell, and proceeds only after a clean verdict; the scanner engine and signature version are stored in a receipt bound to the imported document checksum. Production must supply a real scanner; the library-level injection seam exists so tests can exercise clean and rejected verdicts without external infrastructure. When both artifact-delivery settings are present, a reviewer or read-only auditor may issue an idempotent 30–900 second download grant. The bearer token is HMAC-signed, contains no storage path, is bound to tenant, case, file and approved checksum, requires canonical Base64URL encoding, and rechecks the artifact before returning bytes. Grant and redemption events enter the case audit trail. The signing secret must be held by the deployment secrets service, not committed or sent to a model. No retention duration is assumed. When the host supplies an explicit value from 1 to 3,650 days, a studio administrator may archive a case with a reason. The approved snapshot and artifacts remain intact and downloadable during that window. Deletion is studio-admin-only, revision-bound, and rejected before the recorded cutoff; after the cutoff it purges the exact tenant/case directory and leaves a checksum-protected, idempotent tombstone containing hashes and deletion accountability rather than source content. The canonical `case.json` is written with `case.json.sha256` and is never read before that sidecar verifies. A missing, malformed, mismatched, or symlinked record/checksum pair fails closed instead of allowing a partially written or tampered case to enter a new mutation. Every case locks its statutory, OIC, filing-instruction, disclosure, and taxonomy versions. Statutory, disclosure, presentation, and schedule-taxonomy packs on the MCP and HTTP surfaces come only from deployment configuration; request-selected packs are rejected. ## Reviewed PDF trial-balance intake Trial balances may be supplied as CSV, XLSX, readable PDF, or scanned PDF. A PDF follows a two-stage contract. `ingest-pdf` (service operation `ingest_pdf`, document kind `PDF_TRIAL_BALANCE`) extracts embedded text/table geometry or PaddleOCR tokens into a checksum-bound `PENDING_REVIEW` candidate. It retains page, table, row, source-column, bounding box, extraction method, raw value, OCR confidence, per-page extraction method, and per-table coverage, but creates no canonical accounting entry. Extraction fails closed when any page still requires OCR or any detected table cannot be aligned. A page with no detected table requires an explicit reviewed non-accounting disposition. The authenticated professional then uses `review-pdf-extraction` (service operation `review_pdf_extraction`) to accept or reject the candidate. Acceptance requires all four explicit declarations covering headers/columns, account rows, monetary values, and excluded rows. The review may provide a one-to-one column mapping, cell corrections with reasons, and explicit row exclusions with reasons. A non-account row can be excluded only when all selected monetary fields are zero or blank. A non-zero summary row must identify the accepted account rows it summarizes and reconcile every selected monetary field within the parser tolerance. Only the accepted reviewed rows pass through the existing Decimal normalizer and deterministic trial-balance parser. Debit/credit convention confirmation remains a separate subsequent gate. Run the input-aware dependency check before a PDF import: ```bash python scripts/check_dependencies.py --input ``` Readable PDFs use the core `pdfplumber` and PyMuPDF dependencies. If an image-only PDF needs the optional OCR runtime, the checker returns `OCR_SETUP_REQUIRED`. After explicit user approval, the host may run `python scripts/managed_ocr_runtime.py install`; this installs the separate `requirements-ocr.txt` contract into the persistent shared runtime. PaddleOCR package/model downloads contain no case document bytes. The PDF remains local to the configured case input root; only bounded extracted evidence may enter the selected Vera model context for non-authoritative explanation. The managed runtime accepts exact package pins only and records the installed package versions plus the SHA-256 and size of every required OCR model file; reuse verifies the complete receipt and fails closed after any drift or tampering. A non-first-year case must provide the exact comparative start and end dates; the renderer does not infer a conventional prior year. The selected OIC pack adds its effective professional-review questions to the live questionnaire and workpaper rather than acting as metadata only. A different pack cannot be passed silently to an existing case. A studio administrator may explicitly migrate an open case through `migrate_regulatory_versions` (or the `/regulatory-migrations` HTTP resource). Migration targets are controlled pack identifiers, never caller-supplied rule-pack objects. The migration verifies effective dates and checksums, produces a bounded change report, retains source evidence, invalidates every regulated derived output, and requires full recomputation and revalidation. Approved, exported, archived, and unsupported cases cannot be migrated. Major parser, eligibility, mapping-candidate, statement, schedule, disclosure, note, intelligence, preview, validation, and local-XBRL outputs carry a common computation context: case/revision, input-manifest hash, mapping hash, locked rule versions, regulatory pack checksums, filing campaign, taxonomy checksum, model/template version, and time. This is lineage metadata; it does not make semantic classifications authoritative. Before validation, the case state is derived from controlled coverage rather than conversational judgment: missing or unreconciled structured schedules and answers produce `DATA_GAPS`; once those are complete, the case moves to `NOTE_DRAFT`. Missing narrative remains visible as note work and is not misreported as missing accounting evidence. Every complete non-cash schedule entering an official-taxonomy workflow must also pass `record-schedule-taxonomy-adapter`. The professional binds schedule cells to concepts below the configured official note-table roots. Vera derives the output value from those exact cells, reconciles reused primary facts, rejects concepts outside the table, and requires every remaining cell to carry an explicit reviewed omission reason. A table policy cannot omit every cell. The payable template includes a separately evidenced `secured_amount`, which must be from zero through the row closing balance. The inventory template reconciles opening and closing classes through reviewed increases, decreases, reclassifications, write-downs, reversals, and other movements. Costing method, valuation basis, net-realisable-value, obsolescence, count evidence, and pledged-stock status are required professional inputs; the engine does not infer them. The four assessment fields close only with controlled terminal review states, and the selected statement line must be backed exclusively by reviewed mappings to the selected form's inventory concepts. Reclassifications may cross another balance-sheet class because the movement and opening/closing statement tie-outs, rather than an assumed net-zero rule, provide the mechanical control. Cases default to Italian output (`output_language: "it"`) and may explicitly select English (`"en"`). Accepted narrative blocks and taxonomy text facts must all use that one case language; mixed-language approved output is rejected, and rendered XBRL text facts carry the matching `xml:lang`. The comparative HTML preview uses semantic regions, labelled tables, a skip link, visible keyboard focus, and keyboard-scrollable table regions. These controls do not replace production UI accessibility and screen-reader verification. ## Revision-bound background work Vera may enqueue the declared long-running case operations through `xbrl_case_enqueue_job` and inspect them through `xbrl_case_job_get`. The job identifier is the queue idempotency key. Each record is checksum-verified, tenant-scoped, and bound to the exact source `revision_id`; a result cannot be applied after a newer case revision exists. Execution is deliberately absent from the conversational tool surface. A host worker with the internal `SERVICE_WORKER` role runs one queued item with: ```bash python scripts/run_background_job.py \ --storage-root \ --tenant-id \ --case-id \ --job-id \ [--input-root ] \ [--taxonomy-catalogue ] \ [--taxonomy-package ] \ [--taxonomy-registry ] \ [--intelligence-command-json ''] ``` A failed attempt does not mutate the case. A replay uses the existing mutation idempotency ledger, including recovery when the case mutation completed before the worker could mark the job successful. `taxonomy_catalogue_build` accepts no request-selected paths or entry points; the worker reads the deployment-controlled registry and package, verifies both against the case lock, and stores a checksum-bound case catalogue receipt. `invoke_intelligence` accepts only a task and subject identifiers. It builds the minimum-context packet from the submitted revision, calls the host command over JSON stdin without a shell, stores the exact response inside the protected job for retry recovery, and applies it only if the revision still matches. A concurrent professional edit makes the result `STALE`, and a successful result remains `MODEL_SUGGESTED`. ## Professional review data contracts `xbrl_case_get_review_view` exposes the ten specification review surfaces: case dashboard, source review, mapping grid, statements, schedules, questionnaire, notes editor, issues panel, preview, and approval/export. Account-, anchor-, fact-, schedule-, question-, and issue-heavy views are bounded to at most 500 items per request and include explicit pagination metadata. The approval view never returns the immutable snapshot payload, and preview/export views return resource identifiers and checksums rather than file bytes or arbitrary host paths. The dedicated mapping and questionnaire reads use the same 500-record maximum and explicit pagination. The MCP workpaper read returns only approval and snapshot hashes, its opaque resource identifier, and any exported artifact metadata; the complete immutable snapshot is not copied into model context. Review its contents through the targeted views or issue a separately authorized download grant for the exported `workpaper.json`. Approved export writes the XBRL instance, accessible HTML preview, standalone mapping, issue, and validation reports, the complete workpaper, and a final checksum manifest. The workpaper embeds the checksums of every peer artifact; its own checksum and the manifest checksum remain in the final manifest to avoid recursive self-hashing. ## Optional HTTP adapter `scripts/http_api.py` exposes the section 18 REST resources around the same `CaseService`. It is optional and declares its extra dependency separately in `api-requirements.txt`; normal Vera/MCP operation does not require FastAPI. The host must place an authenticated `RequestContext` in `request.state.vera_request_context` or inject an equivalent trusted provider when constructing the app. Tenant or role headers and JSON fields are never accepted as authentication. Every mutating route requires `Idempotency-Key`; every post-creation mutation also requires the current `revision_id` in `If-Match`. Stale mutations return HTTP 409. ## Controlled taxonomy regression Run the checked-in 24-case synthetic suite with: ```bash python scripts/run_golden_cases.py \ --catalogue \ --taxonomy-package \ --output-dir ``` The runner verifies checksums, renders twenty scenario instances, validates them with offline Arelle, exercises four guarded boundary cases, and writes an artifact manifest. Each XBRL case traverses the public create, ingest, parser, form, mapping, statement, presentation, schedule, schedule-taxonomy, disclosure, narrative, validation, local-XBRL-review, approval, and export lifecycle. It does not transmit files to TEBENI. The scenario suite is complemented by a complete primary-presentation audit: ```bash python scripts/audit_statutory_presentation.py \ --catalogue \ --rule-pack rulepacks/it/statutory-presentation-2026.1.json \ --taxonomy-package \ --instance-output-dir \ --output ``` For ordinary, abbreviated, and micro forms, this derives the exact required leaf and total inventories from the official presentation/calculation networks, applies explicit controlled zero confirmations, renders every resolved primary fact, and requires each instance to pass the pinned offline Arelle validator. The zero-coverage scenario is structural test evidence only; it is not an accounting judgment for a real entity. Audit the selected-form schedule table roots independently with: ```bash python scripts/audit_schedule_taxonomy.py \ --catalogue \ --rule-pack rulepacks/it/schedule-taxonomy-2026.1.json \ --output ``` This verifies the effective adapter pack against the official presentation graph for fixed assets, inventories, receivables, payables, equity, provisions, TFR, taxes, and guarantees/commitments. Reportable item descendants retain their exact role, root, and tuple path so repeated table rows are not flattened into duplicate facts. It proves structural concept eligibility, not the professional classification of an arbitrary client schedule. ## Controlled performance regression Run the maximum supported synthetic trial balance through the production parser, mapping, statement, deterministic-repeat, and validation paths with: ```bash python scripts/benchmark_performance.py \ --output-dir ``` The manifest distinguishes execution-time success from accounting-validation success and leaves provider-backed narrative latency and production review-grid responsiveness explicitly unmeasured. ## Official XBRL 2.1 conformance With the checksum-locked official suite available locally, run: ```bash python scripts/run_xbrl_conformance.py \ --suite-package \ --expected-sha256 00462b833fd064108d0781c601bf2b186db9b85ef950030df9db3ef2f68455e9 \ --output-dir ``` The same `--calc xbrl21` mode is mandatory in the production local validator. The official suite and its generated reports remain controlled run inputs and outputs rather than bundled plugin files.