vssa-clients/references/derived-contractor-registry.md

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.