49 lines
5.2 KiB
Markdown
49 lines
5.2 KiB
Markdown
# 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.
|