Adaptrar, kontrakt och datagränser

xECM rapporterar att dokument 142 har status REJECTED_METADATA. Matrix vill säga att dokumentet är belagt avvisat och att ett processteg påverkas. Mellan dessa två utsagor finns en adapter.

Det är frestande att beskriva adaptern som kod som byter namn på ett fält. Men den gör minst sex saker:

• ansluter med ett bestämt mandat,
• avgränsar tenant, miljö och dataklass,
• hämtar en mängd med känd eller okänd täckning,
• tolkar en leverantörsspecifik status,
• skapar Matrix-identitet, tid och källreferens,
• vägrar eller föreslår handling när förutsättningarna inte håller.

Adaptern är därför både översättare och gränsvakt.

1. Varför gränsen måste vara explicit

Parnas klassiska argument för informationsdöljande är att moduler bör kapsla designbeslut som sannolikt förändras (parnas1972criteria). För en Matrix-adapter är sådana beslut exempelvis:

• vendorobjektets ID-format,
• pagination och rate limits,
• autentiseringsmetod,
• statusvokabulär,
• tidsstämplar och precision,
• fel- och retrysemantik,
• API-version och deprecation,
• vilka fält som innehåller kunddata.

Om dessa detaljer sprids till graf, UI, agenter och regler blir varje vendoruppgradering en systemomfattande migration. Enterprise Integration Patterns beskriver närliggande roller som channel adapters, translators och canonical data models (hohpe2003eip). Matrix behöver samma disciplin, men med extra krav på evidens och handlingsmandat (CLAIM-ADAPTER-001).

En adapter ska alltså exponera en liten Matrix-semantik och hålla det rörliga leverantörskontraktet bakom sig.

2. Sju steg från källa till kunskap

Figur FIG-07-01 visar en säkrare ingestkedja:

FIG-07-01 — Adaptergränsen från extern källa till beslutbar Matrix-artefakt

Visa diagramdefinition

flowchart LR
    X[Externt system<br/>vendor- och kundmodell] --> A[Förvärv<br/>minsta read-scope]
    A --> R[Rått, versionsbundet<br/>underlag]
    R --> N[Versionsbunden<br/>normalisering]
    N --> V{Schema + domän +<br/>tenant/data boundary}
    V -- vägra/quarantine --> F[Synlig refusal<br/>med orsak]
    V -- godkänd --> P[Matrix bundle/event<br/>med sourceRefs]
    P --> C{Coverage gate}
    C -- lucka --> F
    C -- komplett enligt kontrakt --> K[Kunskapslager]
    K --> D[Förklaring och beslut]
    D -. action proposal .-> G[Mänsklig/policygrind]
    G -. separat exekveringsväg .-> W[Write-endpoint i externt system]

1. Förvärv: anropa källan med minsta nödvändiga read-scope.
2. Rå artefakt: bevara versionsbundet svar, cursor och källtid där policyn tillåter det.
3. Normalisering: översätt genom en namngiven adapter- och regelversion.
4. Validering: kontrollera struktur, domäninvariants och identitet.
5. Boundary: verifiera tenant, miljö, zon, klassificering och retention.
6. Publicering: emittera Matrix bundle/event med source refs.
7. Coverage: redovisa vad som sågs, accepterades, vägrades och saknas.

Stegen får gärna köras i samma process, men deras verdicts bör vara separata. Ett HTTP 200 säger bara att förvärvet svarade. Det säger inte att paginationen är komplett, mappningen entydig eller publiceringen tillåten.

3. Rått och normaliserat underlag

Normalisering skapar ett nytt påstående. När REJECTED_METADATA → acceptedByXecm=false måste Matrix kunna visa:

rawSourceRef + revision/digest
vendorSchemaVersion
adapterId + adapterVersion
mappingRuleId + version
normalizedSubjectId
normalizedClaim/event
warnings/refusals
transformedAt

Det råa underlaget behöver inte kopieras in i Matrix. Non-goals förbjuder Matrix som kunddatalager. En source ref kan peka på kundens auktoritativa system eller en skyddad evidensartefakt. Kravet är reproducerbar härledning, inte central datainsamling (CLAIM-ADAPTER-002).

Om källformatet förändras ska gammal normalisering kunna förstås med gammal regelversion. En tyst uppdaterad mapping gör historiska beslut oreproducerbara.

4. Connector-typ, instans och hemlighet

Matrix connector-manifest beskriver en typ: exempelvis vilka förmågor en Unifi- eller xECM-connector kan ha, transport, riktning, riskklass och grind. Den bör kunna ligga i en delad katalog.

En aktiverad instans beskriver däremot:

• tenant och miljö,
• faktisk endpoint eller resource audience,
• aktiverade capabilities,
• ägare och ändringsbeslut,
• lokala freshness- och rate-limit-policyer.

Hemligheter—tokens, client secrets, certifikatnycklar—hör varken hemma i typkatalogen eller kunskapsgrafen. Emittern uttrycker samma princip: target system class delas, medan endpoints och credentials stannar lokalt (MATRIX-INTEGRATION-MAP-EMITTER, CLAIM-ADAPTER-006).

Separationen gör det möjligt att säga "typen stödjer delete" utan att säga "den här instansen får radera".

5. Declare, observe och act

Matrix integrationskarta skiljer tre relationer:

• EMITS: en producer eller läsande capability skapar representation,
• OBSERVES: monitoring/probe observerar systemet,
• ACTS_ON: en action capability kan påverka systemet via grind.

Connector-kontraktet låser producer-capabilities till riskklassen read och actions till reversible eller physical-irreversible. En fysisk irreversibel handling ska alltid ha mänsklig grind (MATRIX-CONNECTOR-CONTRACT).

Detta är mer än taxonomi. Read-token, monitoringidentitet och action-token bör vara olika credentials eller åtminstone olika scopes och code paths. Om en adapter komprometteras ska en läsande ingest inte automatiskt kunna skriva. Matrix non-goals kräver dessutom att ingen extern handling passerar utanför ActionGateway-mönstret (CLAIM-ADAPTER-003).

6. En verklig kontraktslucka

Den aktuella integration-map-emittern sätter explicit ActionGateway (ADR-J001) på alla normaliserade Jake-connectors och skriver grinden på ACTS_ON-kanter. Kända artefakter följer alltså regeln.

Det generella JSON-schemat beskriver samtidigt activationGate som valfritt. Det innehåller ingen root-invariant som kräver fältet när capabilities-arrayen innehåller kind: action. Validatorn schemaslagar de normaliserade manifesterna men lägger i den granskade vägen inte till denna semantiska regel.

Det är en viktig skillnad mellan baslinjen är grön och alla framtida giltiga inputs är säkra. Ett hermetiskt mutationstest 2026-08-11 skickade en reversibel action utan gate genom det levande Draft 2020-12-schemat och fick noll valideringsfel: ACCEPTED_WITHOUT_ACTIVATION_GATE. RESEARCH-016 är därför en rekommenderad, avgränsad backlogkandidat: action ska kräva icke-tom gate medan read-only utan gate fortsatt kan vara giltigt. Runtime ActionGateway ska ändå vara kvar; manifestvalidering och verkställighet är defense in depth.

7. Strukturkontraktets räckvidd

JSON Schema Draft 2020-12 kan uttrycka typer, obligatoriska fält, conditional schemas och arrayvillkor. Specifikationen påpekar samtidigt att strukturell validering kan vara otillräcklig och att format kan fungera som annotation om inte assertionvokabulären verkligen används (jsonschema202012).

Ett schema kan exempelvis bevisa att endpoint är en URI-formad sträng. Det bevisar inte:

• att endpointen tillhör rätt tenant,
• att den går till production i stället för test,
• att credential har rätt scope,
• att API:t faktiskt följer sin dokumentation,
• att alla sidor hämtades,
• att normaliseringen är semantiskt korrekt,
• att en side effect blev rätt utförd.

Schema är en grind, inte hela gränsen (CLAIM-ADAPTER-005).

8. Coverage vid discovery och pagination

En adapter som hämtar sida 1 av 20 kan returnera perfekt giltiga objekt och ändå skapa en falsk helhetsbild. Matrix täckningskontrakt kräver att en mängdoperation skiljer:

expected
observed/covered
skipped with reason
missing
unexpected
refused by validation or boundary

Den rena coverage-primitiven räknar och rapporterar; anroparen definierar vad "verkligheten" är och verkställer domen separat (MATRIX-COVERAGE-CONTRACT).

För ett paginerat xECM-anrop kan nämnaren komma från total count, ett batchmanifest, ett slutcursorbevis eller en uppräkning av partitioner. Om API:t inte erbjuder någon sådan gräns ska adaptern säga täckning okänd, inte komplett (CLAIM-ADAPTER-004).

En robust discovery report bör bära:

• request scope och filter,
• sidor/cursors sedda,
• total enligt källan när den finns,
• unika objekt accepterade,
• dubbletter,
• bortfiltrerade och vägrade per orsak,
• rate-limit eller permission truncation,
• nästa cursor om körningen avbröts.

9. Tenant- och kunskapsgränser

En adaptergräns är samtidigt en säkerhetsgräns. NIST SP 800-207 betonar att tillit inte ska följa enbart av nätverksplats eller ägande; autentisering och auktorisering ska gälla den resurs som nås (nist800207). För Matrix betyder det att "kör på kundens nät" inte är tillräckligt tenantbevis.

Matrix kunskapszoner använder separata collections för öppna och rollbundna zoner, server-side routing och fail-closed refusal när zon saknas eller en frontmatteretikett försöker bredda en restriktiv zon (MATRIX-KNOWLEDGE-ZONES). Detta minskar blast radius jämfört med ett rent metadatafilter.

Indexvakten vägrar kända customers-sökvägar, kundmarkörer och customer: i frontmatter (MATRIX-INDEX-GUARD). Det är värdefullt men inte en komplett innehållsklassificerare. Ett nytt kundnamn eller känsligt innehåll under en tillåten sökväg kan passera. RESEARCH-018 använder endast syntetisk data för att pröva explicit source classification, quarantine och kompletterande DLP-regler (CLAIM-BOUNDARY-001).

10. Kontraktsstandarder som profiler

OpenAPI 3.1.2 kan beskriva HTTP-operationer, schemas, webhooks och security schemes (openapi312). AsyncAPI 3.0 kan beskriva channels, send/receive- operationer, messages, correlation och protokollbindings (asyncapi300). De kan ge Matrix:

• diffbar leverantörsyta,
• genererade klienter och testfixtures,
• kontraktsdrift mellan versioner,
• tydligare scopes och message headers,
• återanvändbar dokumentation.

Men de bör vara profiler runt transportytan, inte ersätta Matrix connector-manifest, riskklass, source refs, coverage eller actiongrind. En OpenAPI-operation som deklarerar DELETE avgör inte om en Matrix-instans får anropa den.

RESEARCH-017 beskriver samma xECM HTTP-operation och JetStream/webhook-flöde i Matrix, OpenAPI och AsyncAPI för att mäta faktisk duplicering och round-trip innan fler format införs.

11. Felmodell och refusal

Adaptern bör klassificera fel efter gräns:

Att fånga allt som "adapter error" förstör nästa handling. Refusal ska bära källa, steg, orsak, retryability, owner och påverkat kunskapsscope.

12. Nordic-adaptern

För Nordic bör xECM-integrationen delas i minst två kapabiliteter:

Läsande receipt producer

• endast read-scope,
• hämtar terminalstatus mot batchmanifest,
• bevarar cursor och rå source ref,
• mappar vendorstatus med versionsbunden regel,
• emitterar observations-/evidensartefakter,
• redovisar 141 accepted, 1 rejected, 0 unknown.

Grindad retry action

• separat action-scope och credential,
• tar dokument-ID, förväntad tidigare status och idempotency key,
• producerar plan/dry-run,
• kräver rätt approval enligt riskklass,
• läser tillbaka xECM-resultatet,
• emitterar action event och verifiering.

Att samma kodpaket kan innehålla båda förmågorna innebär inte att samma runtimeidentitet ska ha båda mandaten.

13. Konsekvenser för gränssnittet

En integrationsvy bör visa mer än "Connected":

1. connector-typ och kontraktsversion,
2. aktiverad instans, tenant och miljö,
3. capabilities uppdelade i read/observe/action,
4. credential-status och scopes utan secretvärden,
5. senaste fullständiga discovery och nästa cursor,
6. accepterat, hoppat, vägrat och okänt,
7. adapter-/mappingversion och källrevision,
8. action gate, riskklass och senaste verifierade handling,
9. datazon, retention och indexeringsförbud,
10. påverkade Matrix-frågor när adaptern är degraderad.

"Connected" utan scope, coverage och senaste verifierade läsning är bara ett transportpåstående.

12. Kontraktsstyrning är en kontrollplansförmåga

Matrix har nu en versionsbunden governanceväg för API-kontrakt. Den sparar baselinehash, klassificerar breaking changes, deprecation och berörda konsumenter och kan vägra en inkompatibel förändring. Det gör ett kontrakt granskningsbart över tid i stället för att bara validera dagens fil (MATRIX-API-CONTRACT-GOVERNANCE).

Avgränsningen är lika viktig: Matrix styr metadata och evidens om kontraktet, inte kundens runtime-API och inte dess payload. Kunddata är fortsatt förbjuden i Matrix index. En grön baseline betyder dessutom att den deklarerade förändringsregeln passerade; den bevisar inte att implementation, deployment eller alla verkliga konsumenter följer kontraktet (CLAIM-ADAPTER-007).

Praktisk granskningslista

1. Kapsla leverantörens identitet och vokabulär bakom adaptern.
2. Separera typ, instans, config och secrets.
3. Ge read, observe och action skilda capabilities och scopes.
4. Bevara rå source ref, adapterversion och mappingregel.
5. Validera struktur och domäninvariants separat.
6. Verifiera tenant, miljö, zon och dataklass server-side.
7. Redovisa pagination, expected set och refusals.
8. Väg in kontrakts-/vendorversion och deprecation.
9. Baselinehasha kontrakt, klassificera breaking changes och namnge konsumenter.
10. Låt action gå via plan, approval, effect och read-back.
11. Mutationstesta saknad gate, fel tenant, cursorloop och okänd status.

Sammanfattning

Adaptern skyddar åt båda håll. Den hindrar leverantörsdetaljer från att bli Matrix kärnsemantik och hindrar Matrix från att läsa, lagra eller påverka mer än den aktiverade instansen tillåter.

Matrix har starka byggstenar: producerregister, connector-riskklasser, EMITS/OBSERVES/ACTS_ON, coveragegrind och server-side kunskapszoner. Reviewen visar samtidigt att action→activationGate ännu är en dokumenterad konvention i generalschemat, inte en full invariant, och att kundmarkörsvakten behöver defense in depth.

Standarder som OpenAPI och AsyncAPI kan beskriva transportytor, men Matrix måste fortsatt äga domain mapping, source refs, coverage, tenantgräns och handlingsmandat. Ett korrekt schemaformat är början på en säker adapter, inte slutet.

Läranderesultat

Efter kapitlet ska studenten kunna:

• beskriva adaptern som semantisk och säkerhetsmässig gräns,
• modellera reproducerbar rå→normaliserad transformation,
• separera connector-typ, instans, hemligheter och capabilities,
• skapa coverage- och refusalrapport för discovery,
• granska tenant-, zon- och kunddatagränser,
• avgränsa OpenAPI/AsyncAPI från Matrix domän- och actionkontrakt.