tenderkit 0.1.0__py3-none-any.whl

tenderkit/sources/mapping.py

@@ -0,0 +1,264 @@
+"""Source-specific fields to the industry-independent Notice model."""
+from collections import defaultdict
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+import html
+import re
+from zoneinfo import ZoneInfo
+
+from tenderkit.model import Award, Lot, Notice
+
+REFERENCE = re.compile(r'4\.1\.2\.\)\s*Numer referencyjny:\s*(.+?)\s+\d\.\d\.\d+\.\)')
+PLATFORM_URL = re.compile(r'Adres strony internetowej prowadzonego post.powania.{0,300}?(https?://\s*\S+|www\.\S+)')
+CPV = re.compile(r'\b(\d{8})(?:-\d)?\b')
+WARSAW = ZoneInfo('Europe/Warsaw')
+# NUTS level 2 -> TERYT voivodeship. Warsaw and the surrounding region share 14.
+NUTS_TERYT = dict(zip(
+    ('PL21', 'PL22', 'PL41', 'PL42', 'PL43', 'PL51', 'PL52', 'PL61', 'PL62', 'PL63', 'PL71', 'PL72', 'PL81', 'PL82', 'PL84', 'PL91', 'PL92'),
+    ('12', '24', '30', '32', '08', '02', '16', '04', '28', '22', '10', '26', '06', '18', '20', '14', '14')))
+
+
+def region(value):
+    if not value:
+        return None
+    value = str(value)
+    if re.fullmatch(r'PL\d{2}', value):
+        return value[2:]
+    if re.fullmatch(r'\d{2}', value):
+        return value
+    return None
+
+
+def ted_region(value):
+    value = first(value)
+    return NUTS_TERYT.get(str(value)[:4]) if value else None
+
+
+def html_to_text(value):
+    return re.sub(r'\s+', ' ', re.sub(r'<[^>]+>', ' ', html.unescape(value or '')))
+
+
+def amount(value):
+    if isinstance(value, list):
+        value = value[0] if value else None
+    try:
+        number = Decimal(re.sub(r'\s', '', str(value)).replace(',', '.'))
+        return number if number.is_finite() and number > 0 else None
+    except InvalidOperation:
+        return None
+
+
+def day(value):
+    return date.fromisoformat(value[:10]) if value else None
+
+
+def instant(value):
+    if not value:
+        return None
+    # TED returns date-only fields with a timezone suffix, e.g. 2026-10-21+02:00.
+    if len(value) <= 16 and 'T' not in value:
+        return datetime.fromisoformat(value[:10] + 'T00:00:00' + value[10:])
+    return datetime.fromisoformat(value.replace('Z', '+00:00'))
+
+
+def bzp_publication_day(value):
+    published = instant(value)
+    if published is None:
+        return None
+    if published.tzinfo is not None:
+        published = published.astimezone(WARSAW)
+    return published.date()
+
+
+def polish(value):
+    if isinstance(value, str):
+        return value
+    if not isinstance(value, dict) or not value:
+        return None
+    text = value.get('pol') or next(iter(value.values()))
+    return text[0] if isinstance(text, list) and text else text or None
+
+
+def first(value):
+    return value[0] if isinstance(value, list) and value else value if not isinstance(value, list) else None
+
+
+def bzp_notice(raw):
+    body = raw.get('htmlBody')
+    text = html_to_text(body)
+    reference, platform = REFERENCE.search(text), PLATFORM_URL.search(text)
+    value = re.search(r'Wartość zamówienia:\s*(\d[\d\s]*(?:,\d+)?)\s*([A-Z]{3})\b', text)
+    description, lots = bzp_scope(body)
+    return Notice(
+        source='BZP', number=raw['noticeNumber'], procedure_id=raw.get('tenderId'),
+        published=bzp_publication_day(raw.get('publicationDate')), deadline=instant(raw.get('submittingOffersDate')),
+        title=raw.get('orderObject'), buyer_name=raw.get('organizationName'),
+        buyer_id=raw.get('organizationNationalId'), buyer_city=raw.get('organizationCity'),
+        buyer_region=region(raw.get('organizationProvince')),
+        cpv=tuple(dict.fromkeys(CPV.findall(raw.get('cpvCode') or ''))),
+        value=amount(value[1]) if value else None, currency=value[2] if value and amount(value[1]) else None,
+        reference=reference[1].strip() if reference else None,
+        platform_url=re.sub(r'\s+', '', platform[1]) if platform else None,
+        url=f"https://ezamowienia.gov.pl/mo-client-board/bzp/notice-details/id/{raw['objectId']}",
+        notice_type=raw.get('noticeType'), raw=raw,
+        description=description, lots=lots,
+        awards=bzp_awards(raw),
+        lot_count=int(re.search(r'Liczba części:\s*(\d+)', text)[1]) if re.search(r'Liczba części:\s*(\d+)', text)
+        else 1 if re.search(r'Możliwe jest składanie ofert częściowych:\s*Nie', text) else None,
+    )
+
+
+def bzp_amendment(raw):
+    text = html_to_text(raw.get('htmlBody'))
+    target = re.search(r'Numer zmienianego ogłoszenia w BZP:\s*(\d{4}/BZP \d+)(?:/(\d+))?', text)
+    if not target:
+        return None
+    version = re.search(r'Identyfikator ostatniej wersji zmienianego ogłoszenia:\s*(\d+)', text)
+    target_number = f'{target[1]}/{target[2] or (version[1] if version else "01")}'
+    deadline = None
+    for label, value in bzp_blocks(raw.get('htmlBody')):
+        if label.startswith('3.4.1.') and re.match(r'8\.1\.\)?\s*Termin składania ofert\b', value):
+            updated = re.search(r'Po zmianie:\s*(\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?)', value)
+            if updated:
+                deadline = datetime.fromisoformat(updated[1]).replace(tzinfo=WARSAW)
+    return Notice('BZP', raw['noticeNumber'], procedure_id=raw.get('tenderId'),
+                  published=bzp_publication_day(raw.get('publicationDate')), deadline=deadline, title=raw.get('orderObject'),
+                  url=f"https://ezamowienia.gov.pl/mo-client-board/bzp/notice-details/id/{raw['objectId']}",
+                  notice_type=raw.get('noticeType'), raw={'amends': target_number})
+
+
+def bzp_blocks(body, labels=None):
+    """(label, value) pairs of one BZP HTML body, the same h3 layout the reader uses."""
+    if not body:
+        return []
+    main = re.search(r'<main\b[^>]*>(.*?)</main>', body, re.S | re.I)
+    if main:
+        body = main[1]
+    found = []
+    for heading, value in re.findall(r'<h3\b[^>]*>(.*?)</h3>(.*?)(?=<h[23]\b|</main>|</body>|$)', body, re.S | re.I):
+        if labels is not None and not labels.search(heading):
+            continue
+        inline = re.findall(r'<span\b[^>]*>(.*?)</span>', heading, re.S | re.I)
+        label = re.sub(r'<span\b[^>]*>.*?</span>', '', heading, flags=re.S | re.I)
+        found.append((html_to_text(label).strip(), html_to_text(' '.join(inline) + ' ' + value).strip()))
+    return found
+
+
+_SCOPE_LABELS = re.compile(r'Krótki opis przedmiotu zamówienia|Część\s+\d|Nazwa części', re.I)
+
+
+def bzp_scope(body):
+    descriptions, titles = [], {}
+    lot_number = None
+    for label, value in bzp_blocks(body, _SCOPE_LABELS):
+        lot = re.fullmatch(r'Część\s+(\d+)(?:\s*[-–—:]\s*(.+))?', label, re.I)
+        if lot:
+            lot_number = lot[1]
+            if lot[2]:
+                titles[lot_number] = lot[2]
+        elif 'krótki opis przedmiotu zamówienia' in label.casefold() and value:
+            descriptions.append(value)
+        elif lot_number is not None and 'nazwa części' in label.casefold() and value:
+            titles[lot_number] = value
+    return '\n\n'.join(dict.fromkeys(descriptions)) or None, tuple(
+        Lot(number, title=title) for number, title in titles.items())
+
+
+def bzp_fields(body):
+    fields = defaultdict(list)
+    for label, value in bzp_blocks(body):
+        code = re.match(r'^(\d+(?:\.\d+)*)\.?\)', label)
+        if code:
+            fields[code[1]].append((label, value))
+    return fields
+
+
+def _one(fields, code):
+    entries = fields.get(code, [])
+    return entries[0][1] if len(entries) == 1 else None
+
+
+def _bid_amount(fields, code):
+    value = _one(fields, code)
+    matched = re.fullmatch(r'\s*([\d\s\u00a0]+,\d{2})\s+(PLN)\s*', value or '')
+    if not matched:
+        return None, None
+    return Decimal(re.sub(r'\s+', '', matched[1]).replace(',', '.')), matched[2]
+
+
+def bzp_awards(raw):
+    """Formal per-lot results from a TenderResultNotice; unparsed sections yield no award, never a guess."""
+    if raw.get('noticeType') != 'TenderResultNotice':
+        return ()
+    body = raw.get('htmlBody') or ''
+    sections = [match for match in re.finditer(r'<h2\b[^>]*>(.*?)</h2>', body, re.I | re.S)
+                if re.search(r'\bSEKCJA\s+V\b', match[1])]
+    published = bzp_publication_day(raw.get('publicationDate'))
+    awards = []
+    for index, section in enumerate(sections):
+        heading = html_to_text(section[1]).strip()
+        content = body[section.end():sections[index + 1].start() if index + 1 < len(sections) else len(body)]
+        fields = bzp_fields(content)
+        status = _one(fields, '5.1')
+        if not status:
+            continue
+        lot = re.search(r'dla części\s+(\d+)(?![\w])', heading, re.I)
+        lot = lot[1] if lot else '__all__'
+        normalized = status.casefold()
+        if 'unieważn' in normalized and 'zawarciem umowy' not in normalized:
+            awards.append(Award(lot=lot, status='CANCELLED', offers=_offer_count(fields), date=published))
+        elif 'zawarciem umowy' in normalized:
+            winner = _one(fields, '7.3.1')
+            if _one(fields, '7.1') != 'Nie':
+                continue    # consortium or unknown structure: do not invent a single contractor
+            price, currency = _bid_amount(fields, '6.4')
+            awards.append(Award(lot=lot, status='AWARDED', contractor=winner,
+                                contractor_id=_one(fields, '7.3.2'), price=price, currency=currency,
+                                offers=_offer_count(fields), date=published))
+    return tuple(awards)
+
+
+def _offer_count(fields):
+    count = _one(fields, '6.1')
+    return int(count) if count and count.isdigit() else None
+
+
+def _ted_texts(value):
+    if isinstance(value, dict):
+        value = value.get('pol') or next(iter(value.values()), None)
+    texts = value if isinstance(value, list) else [value]
+    return tuple(text.strip() for text in texts if isinstance(text, str) and text.strip())
+
+
+def ted_scope(raw):
+    descriptions = _ted_texts(raw.get('description-proc')) + _ted_texts(raw.get('description-lot'))
+    return '\n\n'.join(dict.fromkeys(descriptions)) or None, tuple(dict.fromkeys(_ted_texts(raw.get('title-lot'))))
+
+
+def ted_notice(raw):
+    ids = raw.get('identifier-lot') or []
+    values, currencies = raw.get('estimated-value-lot') or [], raw.get('estimated-value-cur-lot') or []
+    value, currency = amount(raw.get('estimated-value-proc')), first(raw.get('estimated-value-cur-proc'))
+    if value is None and values and all(amount(v) is not None for v in values) and len(set(currencies)) == 1:
+        value, currency = sum(amount(v) for v in values), currencies[0]
+    deadlines = sorted(d for d in raw.get('deadline-receipt-tender-date-lot') or [] if d)
+    urls = [u for u in raw.get('document-url-lot') or [] if u]
+    description, lot_titles = ted_scope(raw)
+    return Notice(
+        source='TED', number=raw['publication-number'], procedure_id=first(raw.get('procedure-identifier')),
+        published=day(raw.get('publication-date')), deadline=instant(deadlines[0]) if deadlines else None,
+        title=polish(raw.get('title-proc')) or polish(raw.get('notice-title')),
+        buyer_name=polish(raw.get('buyer-name')), buyer_city=first(raw.get('organisation-city-buyer')),
+        buyer_id=first(raw.get('organisation-identifier-buyer')),
+        buyer_region=ted_region(raw.get('organisation-country-sub-buyer')),
+        cpv=tuple(dict.fromkeys(str(c).split('-')[0] for c in raw.get('classification-cpv') or [])),
+        value=value, currency=currency if value else None,
+        # Search API arrays are flattened, without a join between each amount
+        # and its lot id. Keep the IDs; never infer per-lot amounts by position.
+        lots=tuple(Lot(str(number)) for number in ids),
+        description=description, lot_titles=lot_titles,
+        reference=first(raw.get('internal-identifier-proc')), platform_url=urls[0] if urls else None,
+        url=f"https://ted.europa.eu/pl/notice/-/detail/{raw['publication-number']}",
+        notice_type=first(raw.get('notice-type')) or 'cn-standard', raw=raw,
+        lot_count=len(ids) or None,
+    )

tenderkit/sources/ted.py

@@ -0,0 +1,116 @@
+"""TED Search API v3 with bounded pagination and completeness checks."""
+from dataclasses import replace
+import re
+import time
+
+from tenderkit.http import Session
+from tenderkit.sources.mapping import ted_notice
+
+TED_SEARCH = 'https://api.ted.europa.eu/v3/notices/search'
+TED_XML = 'https://ted.europa.eu/en/notice/{number}/xml'
+# Search API fields only; the award XML below carries the per-lot join.
+TED_FIELDS = ['publication-number', 'publication-date', 'procedure-identifier', 'title-proc', 'notice-title',
+              'buyer-name', 'organisation-city-buyer', 'internal-identifier-proc', 'document-url-lot',
+              'deadline-receipt-tender-date-lot', 'classification-cpv', 'identifier-lot', 'estimated-value-proc',
+              'estimated-value-cur-proc', 'estimated-value-lot', 'estimated-value-cur-lot',
+              'organisation-country-sub-buyer', 'organisation-identifier-buyer', 'notice-type',
+              'notice-identifier', 'notice-version', 'change-notice-version-identifier',
+              'description-proc', 'description-lot', 'title-lot']
+NOTICE_KINDS = ('cn-standard', 'cn-social', 'pin-cfc-standard')
+RESULT_KINDS = ('can-standard',)
+SEARCH_KINDS = NOTICE_KINDS + RESULT_KINDS
+MAX_AWARD_XML = 1000
+
+
+class TedIncomplete(RuntimeError):
+    """The source did not return exactly its declared set of publications."""
+
+
+def cpv_condition(codes):
+    if any(not re.fullmatch(r'\d{1,8}\*?', code) for code in codes):
+        raise ValueError('Invalid CPV')
+    terms = [f'classification-cpv={code}' for code in codes]
+    return terms[0] if len(terms) == 1 else '(' + ' OR '.join(terms) + ')' if terms else ''
+
+
+def fetch_notices(session, start, end, codes=(), kinds=('cn-standard',), *, mapper=ted_notice,
+                  max_pages=100, delay=1.0):
+    if start > end or not 1 <= max_pages <= 100:
+        raise ValueError('Invalid TED window or pagination limit')
+    if not kinds:
+        return []
+    if any(not re.fullmatch(r'[a-z][a-z0-9-]{0,50}', k) for k in kinds):
+        raise ValueError('Invalid TED notice type')
+    terms = ['buyer-country=POL', cpv_condition(codes)]
+    kinds_query = [f'notice-type={k}' for k in kinds]
+    terms.append(kinds_query[0] if len(kinds_query) == 1 else '(' + ' OR '.join(kinds_query) + ')')
+    terms += [f'publication-date>={start:%Y%m%d}', f'publication-date<={end:%Y%m%d}']
+    query = ' AND '.join(t for t in terms if t)
+    rows, seen, expected = [], set(), None
+    for page in range(1, max_pages + 1):
+        for attempt in range(6):
+            response = session.post(TED_SEARCH, json=dict(query=query, fields=TED_FIELDS, limit=250, page=page), timeout=90)
+            if response.status_code != 429:
+                break
+            time.sleep(10 * (attempt + 1))
+        response.raise_for_status()
+        body = response.json()
+        batch, total = body['notices'], body.get('totalNoticeCount')
+        if not isinstance(batch, list):
+            raise ValueError('Expected TED notices array')
+        if total is not None:
+            if not isinstance(total, int) or total < 0 or expected is not None and total != expected:
+                raise TedIncomplete('TED total changed during pagination')
+            expected = total
+            if expected > 15000:
+                raise TedIncomplete('TED pagination supports 15000 notices; use a narrower window or profile')
+        for raw in batch:
+            number = raw['publication-number']
+            if number in seen:
+                raise TedIncomplete('TED repeated a publication during pagination')
+            seen.add(number)
+            rows.append(mapper(raw))
+        if expected is not None and len(rows) == expected:
+            return rows
+        if len(batch) < 250:
+            if expected is not None and len(rows) != expected:
+                raise TedIncomplete(f'{len(rows)} notices fetched, TED counts {expected}')
+            return rows
+        time.sleep(delay)
+    raise TedIncomplete('TED pagination safety limit reached')
+
+
+class Ted:
+    name = 'TED'
+
+    def __init__(self, session=None, xml_delay=1.0):
+        self.session = session or Session()
+        self.xml_delay = xml_delay
+
+    def fetch(self, start, end, query):
+        known = tuple(k for k in query.notice_types if k in SEARCH_KINDS)
+        kinds = known or NOTICE_KINDS
+        if query.include_results:
+            kinds = kinds + tuple(k for k in RESULT_KINDS if k not in kinds)
+        # SourceQuery carries prefixes; append * to short codes, keep full codes exact.
+        codes = tuple(p + '*' if len(p) < 8 else p for p in query.cpv_prefixes)
+        notices = fetch_notices(self.session, start, end, codes, kinds)
+        if not any(kind in kinds for kind in RESULT_KINDS):
+            return notices
+        results = [notice for notice in notices if notice.notice_type in RESULT_KINDS]
+        if len(results) > MAX_AWARD_XML:
+            raise TedIncomplete(f'{len(results)} TED award notices exceed the {MAX_AWARD_XML} XML budget; narrow the window')
+        return [self.awards(notice) if notice.notice_type in RESULT_KINDS else notice for notice in notices]
+
+    def awards(self, notice):
+        """Fill per-lot awards from the notice XML; a failed fetch keeps the search-API record intact."""
+        try:
+            if self.xml_delay:
+                time.sleep(self.xml_delay)
+            response = self.session.get(TED_XML.format(number=notice.number),
+                                        headers={'Accept': 'application/xml'}, timeout=90)
+            response.raise_for_status()
+            from tenderkit.sources.ted_xml import parse_awards
+            return replace(notice, awards=parse_awards(response.content))
+        except (OSError, ValueError, RuntimeError):
+            return notice

tenderkit/sources/ted_xml.py

@@ -0,0 +1,97 @@
+"""Per-lot awards from the public TED notice XML (eForms UBL).
+
+The Search API arrays are flattened and carry no join between a lot and its winner, so multi-lot
+awards come from the authoritative XML behind `https://ted.europa.eu/en/notice/{number}/xml`.
+Only the NoticeResult section is read; missing fields stay empty instead of being inferred.
+"""
+from datetime import date
+from decimal import Decimal, InvalidOperation
+import xml.etree.ElementTree as ET
+
+from tenderkit.model import Award
+
+NS = {
+    'cac': 'urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2',
+    'cbc': 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2',
+    'efac': 'http://data.europa.eu/p27/eforms-ubl-extension-aggregate-components/1',
+    'efbc': 'http://data.europa.eu/p27/eforms-ubl-extension-basic-components/1',
+}
+AWARDED_STATUS = 'selec-w'
+
+
+def text(element, path):
+    found = element.find(path, NS) if element is not None else None
+    value = (found.text or '').strip() if found is not None and found.text else None
+    return value or None
+
+
+def money(element):
+    node = element.find('cac:LegalMonetaryTotal/cbc:PayableAmount', NS) if element is not None else None
+    if node is None or not (node.text or '').strip():
+        return None, None
+    try:
+        value = Decimal(node.text.strip())
+    except InvalidOperation:
+        return None, None
+    return (value, node.get('currencyID')) if value.is_finite() and value >= 0 else (None, None)
+
+
+def parse_awards(document):
+    """Award tuples for one ContractAwardNotice XML document; raises ValueError when it is not one."""
+    try:
+        root = ET.fromstring(document)
+    except ET.ParseError as exc:
+        raise ValueError('Unreadable TED notice XML') from exc
+    if root.tag.rsplit('}', 1)[-1] not in ('ContractAwardNotice', 'ContractAwardNoticeType'):
+        raise ValueError('Not a TED contract award notice')
+    organizations = {}
+    for company in root.findall('.//efac:Organizations/efac:Organization/efac:Company', NS):
+        key = text(company, 'cac:PartyIdentification/cbc:ID')
+        if key:
+            organizations[key] = (text(company, 'cac:PartyName/cbc:Name'),
+                                  text(company, 'cac:PartyLegalEntity/cbc:CompanyID'))
+    tenders = {}
+    for tender in root.findall('.//efac:NoticeResult/efac:LotTender', NS):
+        key = text(tender, 'cbc:ID')
+        if key:
+            price, currency = money(tender)
+            tenders[key] = dict(tenderer=text(tender, 'efac:TenderingParty/cbc:ID'), price=price, currency=currency)
+    contracts = {}
+    for contract in root.findall('.//efac:NoticeResult/efac:SettledContract', NS):
+        key, issued = text(contract, 'cbc:ID'), text(contract, 'cbc:IssueDate')
+        if key and issued:
+            try:
+                contracts[key] = date.fromisoformat(issued[:10])
+            except ValueError:
+                pass
+    parties = {}
+    for party in root.findall('.//efac:NoticeResult/efac:TenderingParty', NS):
+        key, organization = text(party, 'cbc:ID'), text(party, 'efac:Tenderer/cbc:ID')
+        if key and organization:
+            parties[key] = organization
+    awards = []
+    for result in root.findall('.//efac:NoticeResult/efac:LotResult', NS):
+        lot = text(result, 'efac:TenderLot/cbc:ID')
+        if not lot:
+            continue
+        tender = tenders.get(text(result, 'efac:LotTender/cbc:ID')) or {}
+        contractor, contractor_id = organizations.get(parties.get(tender.get('tenderer')), (None, None))
+        awarded = text(result, 'cbc:TenderResultCode') == AWARDED_STATUS
+        awards.append(Award(
+            lot=lot, status='AWARDED' if awarded else 'CANCELLED',
+            contractor=contractor if awarded else None,
+            contractor_id=contractor_id if awarded else None,
+            price=tender.get('price') if awarded else None,
+            currency=tender.get('currency') if awarded else None,
+            offers=subscription_count(result),
+            date=contracts.get(text(result, 'efac:SettledContract/cbc:ID')) if awarded else None))
+    return tuple(awards)
+
+
+def subscription_count(result):
+    for statistics in result.findall('efac:ReceivedSubmissionsStatistics', NS):
+        if text(statistics, 'efbc:StatisticsCode') == 'tenders':
+            value = text(statistics, 'efbc:StatisticsNumeric')
+            if value and value.isdigit():
+                return int(value)
+    return None

tenderkit/store/__init__.py

@@ -0,0 +1 @@
+"""Local persistence, independent of pharma's database."""

tenderkit/store/documents.py

@@ -0,0 +1,168 @@
+"""Verified SHA-256 publication shared with pharma, plus the standalone sharded store."""
+import hashlib
+import os
+from pathlib import Path
+import re
+import json
+import tempfile
+import shutil
+
+from tenderkit.limits import MAX_BYTES
+
+STORAGE_NAME = re.compile(r'([a-f0-9]{64})\.[a-z0-9]+')
+
+class StoreError(ValueError):
+    pass
+
+
+class PathTooLong(StoreError):
+    """A store path that Windows would refuse (MAX_PATH); code PATH_TOO_LONG is what a download job reports."""
+    code = 'PATH_TOO_LONG'
+
+
+# Windows refuses paths of 260 characters or more unless long paths are enabled for the machine and Python; a store in a
+# deep directory then failed with a bare FileNotFoundError (issue #23). Other systems allow far longer paths.
+MAX_PATH = 259 if os.name == 'nt' else 4095
+
+
+def check_length(path, limit=None):
+    """The path, or PathTooLong naming its length and the remedy."""
+    limit = MAX_PATH if limit is None else limit
+    if len(str(path)) > limit:
+        raise PathTooLong(f'PATH_TOO_LONG: {len(str(path))} characters (limit {limit}): {path}. '
+                          'Choose a shorter --documents-dir or TENDERKIT_DOCUMENT_DIR.')
+    return path
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with Path(path).open('rb') as stream:
+        for block in iter(lambda: stream.read(1 << 20), b''):
+            digest.update(block)
+    return digest.hexdigest()
+
+def state(store, storage_name, digest, size=None):
+    """'OK', 'MISSING' or 'MISMATCH' (other content or size) for one registered document."""
+    path = Path(store)/storage_name
+    if not path.is_file():
+        return 'MISSING'
+    if (size is not None and path.stat().st_size != size) or sha256_file(path) != digest:
+        return 'MISMATCH'
+    return 'OK'
+
+def publish(store, source, digest, storage_name):
+    """Copy a verified source into the store; True when written, False when the same content is already there.
+
+    The copy goes to a temporary file in the store, is checked and only then renamed, so a reader never sees a partial
+    file. An existing file with other content is an error and is never overwritten.
+    """
+    found = STORAGE_NAME.fullmatch(storage_name or '')
+    if not found or found[1] != digest:
+        raise StoreError(f'Storage name does not match its SHA-256: {storage_name}')
+    if sha256_file(source) != digest:
+        raise StoreError(f'Source does not match its SHA-256: {Path(source).name}')
+    store = Path(store)
+    target = store/storage_name
+    current = state(store, storage_name, digest)
+    if current == 'OK':
+        return False
+    if current == 'MISMATCH':
+        raise StoreError(f'Store holds other content under {storage_name}')
+    store.mkdir(parents=True, exist_ok=True)
+    temporary = store/f'.{storage_name}.{os.getpid()}.tmp'
+    try:
+        with Path(source).open('rb') as reader, temporary.open('xb') as writer:
+            for block in iter(lambda: reader.read(1 << 20), b''):
+                writer.write(block)
+            writer.flush()
+            os.fsync(writer.fileno())
+        if sha256_file(temporary) != digest:
+            raise StoreError(f'Copy does not match its SHA-256: {storage_name}')
+        # Content-addressed: a concurrent writer of the same name wrote the same bytes.
+        os.replace(temporary, target)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return True
+
+
+class DocumentStore:
+    def __init__(self, root):
+        self.root = Path(root).expanduser().resolve()
+
+    def path(self, storage_name):
+        if not STORAGE_NAME.fullmatch(storage_name or ''):
+            raise StoreError('Invalid storage name')
+        path = self.root / 'objects' / storage_name[:2] / storage_name
+        if not path.resolve().is_relative_to(self.root):
+            raise StoreError('Document escapes store')
+        return check_length(path)
+
+    def put(self, source):
+        source = Path(source)
+        if source.stat().st_size > MAX_BYTES:
+            raise StoreError('Document exceeds file size limit')
+        digest = sha256_file(source)
+        ext = re.sub(r'[^a-z0-9]', '', source.suffix.lower())[:10] or 'bin'
+        name = f'{digest}.{ext}'
+        target = self.path(name)
+        publish(target.parent, source, digest, name)
+        return dict(sha256=digest, storage_name=name, byte_size=target.stat().st_size)
+
+    def verified(self, record):
+        path = self.path(record['storage_name'])
+        if state(path.parent, path.name, record['sha256'], record['byte_size']) != 'OK':
+            raise StoreError('Stored document is missing or corrupt')
+        return path
+
+    def manifest(self, source, number, value):
+        key = hashlib.sha256(json.dumps([source, number], ensure_ascii=False).encode('utf-8')).hexdigest()
+        directory = self.root / 'procedures' / key / 'raw'
+        if not directory.resolve().is_relative_to(self.root):
+            raise StoreError('Manifest escapes store')
+        # manifest.json and its temporary file must fit as well as the linked documents.
+        check_length(directory / ('x' * 24 + '.tmp'))
+        directory.mkdir(parents=True, exist_ok=True)
+        for item in value['documents']:
+            if not item.get('localPath'):
+                continue
+            source = Path(item['localPath'])
+            digest = item['sha256']
+            if sha256_file(source) != digest:
+                raise StoreError('Manifest source does not match its SHA-256')
+            # Existing pharma readers resolve raw/Path(localPath).name. Keep
+            # that layout as hard links to the canonical sharded objects.
+            # The readable part of the name shrinks to fit the path limit; the digest prefix keeps names unique.
+            suffix = source.suffix
+            room = MAX_PATH - len(str(directory)) - len(os.sep) - 17 - len(suffix)
+            safe = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '_', item['name']).strip(' .')
+            if Path(safe).suffix.lower() == suffix.lower():
+                safe = safe[:len(safe) - len(suffix)]
+            safe = safe[:max(0, min(80, room))].strip(' .') or 'document'
+            target = check_length(directory / (digest[:16] + '_' + safe + suffix))
+            if target.exists():
+                if sha256_file(target) != digest:
+                    raise StoreError('Manifest file holds other content')
+            else:
+                try:
+                    os.link(source, target)
+                except OSError:
+                    with tempfile.NamedTemporaryFile(dir=directory, suffix='.tmp', delete=False) as stream:
+                        temporary_copy = Path(stream.name)
+                    try:
+                        shutil.copyfile(source, temporary_copy)
+                        if sha256_file(temporary_copy) != digest:
+                            raise StoreError('Manifest copy does not match SHA-256')
+                        os.replace(temporary_copy, target)
+                    finally:
+                        temporary_copy.unlink(missing_ok=True)
+            item['localPath'] = str(target)
+        path = directory / 'manifest.json'
+        with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', dir=directory, suffix='.tmp', delete=False) as stream:
+            temporary = Path(stream.name)
+            json.dump(value, stream, ensure_ascii=False, indent=1)
+            stream.flush()
+            os.fsync(stream.fileno())
+        try:
+            os.replace(temporary, path)
+        finally:
+            temporary.unlink(missing_ok=True)
+        return path