# Read-only portfolio source inventory and canonical-source selection

Use this procedure when a finance sprint must identify a canonical portfolio source from sensitive candidate PDFs, DOCX files, CSV exports, or similar downloads without exposing customer data.

## Output contract first

Before inspection, convert the request into an explicit disclosure allowlist. A typical sanitized structural report may reveal only:

- candidate slot/ordinal, never filename;
- coarse source class;
- evidenced dates and whether each is a snapshot, period endpoint, document-metadata date, or transaction date;
- portfolio/account count;
- security-position and cash-row counts;
- semantic-field presence;
- reconciliation and parser determinism assessments;
- format rules such as encoding, delimiter, quoting, decimal convention, and date grammar.

Never emit raw rows, excerpts, headings, document text, customer/account/portfolio labels, filenames, identifiers, holdings, amounts, or personal metadata. For PDF/DOCX, report only derived structure and semantics—do not quote content. Keep sensitive text inside the local inspection process and print only allowlisted aggregates.

## Read-only inspection workflow

1. Discover candidate slots and containers without renaming, copying, converting, or editing source files.
2. Confirm actual container type independently of extension. Record page count, table shape, encoding, and row/column counts only.
3. Extract in memory or to stdout:
   - PDF: text extraction with layout preservation; inspect metadata only through sanitized predicates.
   - DOCX: read the ZIP/XML package directly when possible; preserve paragraph, table-row, and cell boundaries. Avoid conversion artifacts.
   - CSV: decode bytes explicitly, detect BOM, sniff a constrained delimiter set, and parse with a real CSV parser rather than splitting lines.
4. Run deterministic recognizers locally for dates, ISINs, currency codes, numeric cells, table/header roles, cash rows, subtotals, and grand totals. Emit counts/booleans, not matched strings.
5. Classify every candidate into one of: official e-tax statement, official interim statement, position export, or other. Do not infer “official” merely from branding, PDF format, or a polished layout; require document semantics or provenance evidence.
6. Separate security positions from cash and from transaction rows. An ISIN-bearing transaction is not a snapshot position.
7. Determine account cardinality only from an explicit account/portfolio field or unambiguous document scope. If no label exists, report one undifferentiated export scope and state that account count is not evidenced.
8. Evaluate reconciliation and parsing independently. A file can be mechanically parseable but unsuitable for position reconciliation.
9. Check the user-requested target date directly across all candidates, including alternate numeric and month-name forms. Do not substitute file creation/modification time for a financial snapshot date.
10. Finish with a single canonical recommendation, or state that none qualifies. If the best source is usable only for a different date, say both facts explicitly.

## Date semantics

Keep these meanings distinct:

- **Snapshot/as-of date:** governs positions, cash, prices, and source total.
- **Period endpoint:** latest point in a performance series; not necessarily a holdings snapshot.
- **Transaction date:** dates ledger events; not a closing-position date.
- **Document metadata date:** creation/modification timestamp; provenance evidence only unless the document explicitly binds it to the statement.

Summarize long date series as a range and cadence. Never list hundreds of transaction or performance dates when the structural question only needs coverage and the latest evidenced date.

## Semantic field matrix

For each candidate, report availability of:

- portfolio/account label;
- instrument name;
- ISIN;
- quantity;
- asset type/group;
- currency;
- price and value;
- source subtotal/grand total;
- cash balance or cash rows.

Qualify overloaded fields. For example, transaction quantity is not position quantity, allocation percentage is not monetary value, and cash-flow amount is not closing cash.

## CSV contract reporting

Report delimiter, quote character, encoding/BOM, date grammar, decimal separator, sign convention, and semantic column roles in ordinal order. Do not quote raw headers. Validate roles with both sanitized header matching and value profiles (ISO-date percentage, ISIN validity, ISO-currency shape, numeric percentage, and distinct-count behavior). Empty-but-declared fee/tax columns should be reported as structurally present but empty.

## Reconciliation grades

- **Strong:** security values plus cash reconcile through component totals to a source grand total for the same snapshot date.
- **Partial:** allocation totals or transaction arithmetic can be checked, but no complete position/cash total exists.
- **None:** required components or source totals are absent.

A canonical position source normally requires an evidenced as-of date, account scope, instrument identity, quantities, currency, valuation fields, cash treatment, and a source total. If the sprint requires a particular date, a structurally excellent source for another date is only a dated baseline—not a date-aligned canonical source.

## Parser determinism

Call parsing unambiguous only when row classes and semantic roles can be separated deterministically. For merged DOCX tables, define explicit row classes: title/metadata, repeated headers, security positions, cash positions, subtotals, and grand total. For transaction CSVs, say “unambiguous as a transaction ledger” rather than implying suitability as a position snapshot.

## Final verification

- No source file was written, renamed, converted, or moved.
- No prohibited value reached tool summaries or the final response.
- Position-row counts exclude headers, totals, and transaction events; cash counts are separate.
- Target-date evidence is explicit and uses financial date semantics.
- Recommendation distinguishes “best available baseline” from “meets required snapshot date.”