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.

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.