# Derived contractor registry method

Use this when canonical client-system observations contain contractor/provider text and the documentation needs a cross-client contractor view.

## Evidence model

Treat the contractor registry as a **derived view**, never as a second editable evidence store. Every relationship must retain:

- exact canonical client and system identity;
- explicitly named contractor/provider entity;
- bounded role as stated by the source (developer, implementer, service provider, licensor, host, support supplier, consortium member, public-sector operator, etc.);
- direct evidence URL and confidence;
- historical/current/planned context where known.

Do not turn `Not publicly identified`, “suppliers not named”, descriptive prose, or an ambiguous composite phrase into entities. Do not silently upgrade one role into another: development does not prove hosting or current support.

Classify the entity itself before deriving a contractor card. A ministry, agency, authority, or other government body does not become a contractor merely because an observation calls it an operator, centralized service provider, platform owner, or public-sector implementer. If that body is itself an investigation subject, retain it in the Clients registry and preserve its exact service relationship as observation text, but exclude it from `CTR-*` extraction and contractor links. Research its own systems and commercial delivery partners from its Client dossier. Add an explicit, reviewed exclusion rule when free-text parsing would otherwise promote the body; do not hide the relationship or rewrite the public agency as a commercial supplier.

## Identity and stable routes

Normalize only safe textual differences for matching. Preserve the displayed source name and keep ambiguous composites separate until evidence supports a split or merge. Generate stable `CTR-*` IDs and slugs from a durable normalized identity key rather than sequence position. Sequence numbers may order generated files but must not define identity.

Before adding or changing a contractor label in a canonical observation, inspect the current derived registry and all existing near-name observations. Reuse the established exact label only when it denotes the same evidenced entity. Treat a standalone company and a composite such as `„Company“ su konsorciumo partneriais` as separate identities unless reviewed evidence supports a merge. Legal-designator changes (`UAB`, `AB`, quotation style) can create a new deterministic identity; do not introduce them casually. After regeneration, compare the entity count and inspect near-name groups. An unexpected increase is an identity-collision warning, not evidence that a new contractor was discovered.

A contractor dossier should list exact system/client relationships, bounded roles, confidence, and direct sources. A system dossier should expose its evidenced contractors, but the underlying client observation remains canonical.

## Implementation sequence

1. Write focused failing tests for named-entity extraction, unknown-placeholder exclusion, multi-contractor splitting, stable IDs/slugs, relationship aggregation, and one representative evidence-backed system.
2. Implement extraction and aggregation without editing generated pages directly.
3. Generate contractor overview/registry, individual dossiers, and machine-readable JSON.
4. Add a separate documentation collection with first-level **Overview** and expanded **Registry**, plus navbar/footer/search integration.
5. Add build invariants: JSON exists, IDs/slugs are unique, route count matches entity count, every relationship resolves to valid client/system IDs, and representative evidence is present.
6. Run focused tests, registry validation, type checking, full production build, and rendered browser checks for both a system page and contractor page.
7. After publishing, verify local/remote ref equality, exact CI run success, authenticated source readback, and deployed route behavior. An expected authentication redirect proves the access boundary is active, not page content; use successful CI publication and an authorized/backend content check when available before claiming deployed content.

## Lifecycle evidence interaction

A dated official announcement whose title/body explicitly says a named system started operating, launched, or went live can establish a production-release date at the source’s stated precision. This is different from generic page publication/update metadata. Quote the operational statement, cite corroborating announcements, and use the earliest date that explicitly establishes operation when official announcements differ. Do not infer delivery kickoff from go-live; kickoff needs separate evidence.

## Common pitfalls

- Parsing every capitalized phrase or semicolon clause as a company.
- Merging legal-name variants or consortium descriptions without reviewed identity evidence.
- Showing a contractor on a system page without retaining the source relationship.
- Presenting a historical creation supplier as the current maintainer.
- Claiming deployment verification solely from an unauthenticated redirect to an identity provider.
- Adding navigation without search indexing, generated-route validation, or machine-readable output.