# ERC-software: implementatie van Realix Resources v1 Dit document is de overdracht voor een chat in het ERC-codeproject. Het beschrijft het gebouwde contract. Controleer vóór implementatie de bereikbaarheid van het manifest; de definitieve publicatiestatus staat in docs/resources-operations.md van het RealixWebsite-project. Deze wijziging bevat zelf geen ERC-code. ## Startadres en bronnen Het vaste startadres voor nieuwe software is: https://resources.realix-erc.com/v1/manifest.json De leesbare overzichtspagina staat op https://resources.realix-erc.com/ en deze handleiding op https://resources.realix-erc.com/implementation.md. | Bron | Endpoint | Inhoud | | --- | --- | --- | | Manifest | /v1/manifest.json | Locaties, formaatversies en integriteitsgegevens | | Releases | /v1/releases.json | Zes product/platformcombinaties en bestaande releasehistorie | | Templates | /v1/templates.json | Drie projecten en geverifieerde ZIP-bestanden | | Designer AI | /v1/designer-ai-index.json | KB-artikelen, topics, regels en verwijzingslinks | | Handleidingen | /v1/documents.json | Twee Evaluation Kit-PDFs | | Schemas | /v1/schemas/{manifest,releases,templates,designer-ai-index,documents}.schema.json | JSON Schema 2020-12 | | Bestanden | /files/{sha256}/{url-encoded-filename} | Installers, ZIPs en PDFs | De catalogus-URLs in het manifest zijn leidend. De tabel dient als uitleg en diagnostiek; hardcode deze afzonderlijke URLs niet in de client. ## Manifestcontract Alle JSON-bronnen hebben schemaVersion (momenteel 1), revision en updatedAt. revision is een opaque wijzigingskenmerk met de vorm sha256: gevolgd door 64 hexadecimale tekens. Vergelijk het als string; probeer geen volgorde af te leiden. updatedAt is UTC en beschrijft de bronpublicatie/capture, niet het tijdstip van iedere HTTP-aanvraag. Het manifest bevat releases, templates, knowledge, documents en links. Een catalogusdescriptor bevat: - catalogUrl; knowledge gebruikt indexUrl; - schemaVersion, revision en updatedAt van de betreffende catalogus; - sha256 en sizeBytes van de volledige UTF-8-responsbytes; - schemaUrl met het contract van die catalogus. knowledge.articleBaseUrl geeft de actuele publieke artikelbasis. Tot de apex-omschakeling is dat https://realix-website-migration.wesleyvanderbu732195.chatgpt.site/knowledge-base/. Daarna kan het https://realix-erc.com/knowledge-base/ worden. Neem beide exacte HTTPS-bases op in de vertrouwde configuratie; autoriseer geen willekeurige host omdat deze in JSON staat. De D1-indexUrl is content-addressed onder /v1/knowledge/{revision-hash}.json; oudere manifestrevisies blijven bruikbaar. templates.downloadBaseUrl is https://resources.realix-erc.com/files/ en is informatief: gebruik voor downloaden altijd de volledige file.url per item. Deze nieuwe catalogus gebruikt geen basis-URL-plus-filename-berekening. links bevat downloads, support en implementation. schemaVersion is onafhankelijk per bron. Accepteer versie 1 en onbekende optionele velden; weiger een onbekende hoofdversie met een begrijpelijke melding. Geen enkel JSON-veld bevat een authenticatietoken of geheim. ## Bestanden en templates file bevat url, filename, sizeBytes en sha256. filename is alleen een zichtbare naam of veilige lokale bestandsnaam, nooit een relatief pad uit te voeren. De server heeft de volledige bronbestanden gekopieerd en gehasht. Een hash die via dezelfde HTTPS-bron wordt geleverd bewijst integriteit, geen onafhankelijke authenticiteit. Installerondertekening blijft een afzonderlijke controle. Templates hebben een vaste id, title, description, version, modifiedAt, minimumDesignerVersion en file. De bestaande bron bevat geen betrouwbare eigen templateversies of minimale Designer-versie. Die velden zijn daarom null. modifiedAt is de oorspronkelijke catalogusdatum en is geen versiegrens. Gebruik file.sha256 om een gewijzigde template te herkennen. Download naar een tijdelijk bestand, controleer maximumgrootte, werkelijke sizeBytes en SHA-256, en maak de download pas daarna beschikbaar. Range/HEAD en hervatten worden ondersteund; valideer altijd opnieuw de volledige eindhash. Controleer bij uitpakken dat elk ZIP-pad binnen de gekozen projectmap blijft; weiger absolute paden, ..-traversal en ontsnappende links. Behoud de bestaande projectimportsemantiek, waaronder de huidige behandeling van de hoofdmap. ## Versies, release notes en compatibiliteit releases.products heeft deze vaste IDs: | ID | Applicatie | Platform | | --- | --- | --- | | server-windows | Server | Windows | | designer-windows | Designer | Windows | | gamehost-windows | Game Host | Windows | | audiobox-windows | Audio Box | Windows | | mediabox-windows | Media Box | Windows | | mediabox-raspberry-pi | Media Box | Raspberry Pi | De productrecords bevatten applicationId, platform, architecture, availableDownload, historyId, documentationStatus en serverCompatibility. architecture is voorlopig null; leid geen CPU-architectuur af uit een naam. availableDownload.version komt uit de daadwerkelijk aangeboden publieke installer, en availableDownload.file verwijst naar de gekopieerde bytes. histories bevat afzonderlijk de letterlijk overgenomen bestaande versiehistorie. historyId koppelt een product aan die historie. Een historisch release-item heeft version, releasedAt, channel (stable/beta), notes, serverCompatibility en legacyCompatibilityText. De bestaande bronnen spreken elkaar gedeeltelijk tegen: de downloadpagina biedt Server/Designer 3.2.0.0, Game Host 2.2.1.2 en Audio Box 2.4.0.0, terwijl het Markdown-versiebestand voor die producten oudere versies documenteert. De catalogus houdt beide feiten zichtbaar. documentationStatus betekent: - matched: de aangeboden versie heeft een overeenkomend historisch record; - version-not-documented: release notes/compatibiliteit voor deze downloadversie ontbreken; gebruik nooit die van de vorige versie; - platform-unspecified: de MediaBox-historie maakt het platform niet expliciet. serverCompatibility is null als de overeenkomst ontbreekt of het platform onduidelijk is. Null betekent onbekend, niet onbeperkt en niet onverenigbaar. Voor Server zelf is een serverafhankelijkheid niet van toepassing. De oudere lijsten met drie versies blijven bewaard in legacyCompatibilityText; zij zijn niet stilzwijgend omgezet naar een min/max-bereik. Vergelijk vierdelige productversies numeriek als vier integers (System.Version), nooit lexicografisch of als generieke drieledige semver. Bestaande min/max- servergrenzen zijn driedelig en inclusief; vergelijk daarvoor major/minor/build. Dit is een bewuste wijziging ten opzichte van de oude evaluatie die bij een update-indicatie ook het vierde versiedeel negeert. Test dat onderscheid. De aangeboden download heeft geen geverifieerd stable/beta-label of releasedatum wanneer die versie ontbreekt in de historie. Laat de software daarop geen automatische update/installatie of compatibiliteitsbeslissing baseren. Een beschikbare download kan wel als zodanig worden getoond. ## Designer AI De nieuwe index bewaart purpose, scannedSourceDate, useRules, knowledgeBase, referralLinks en answerProcedure. knowledgeBase-items hebben title, url en topics. Nieuwe schema-/revisiemetadata staat erbij; de artikelinhoud zelf blijft op de website. Voor de D1-index geeft scannedSourceDate de generatiedatum aan. source.kind is sites-d1; source.contentRevision omvat actuele gepubliceerde artikelversies, inhoudshashes, topics en beleid. source.capturedAt en updatedAt geven de generatie van die revisie aan. Dit is geen handmatige inhoudsreview. Haal eerst de index op en accepteer daarna alleen exacte knowledgeBase-URLs uit die gevalideerde index. Artikel-URLs vallen exact onder de vooraf vertrouwde knowledge.articleBaseUrl, zonder querystring, fragment, credentials of redirect. Handhaaf deze beperking; referralLinks zijn geen toegestane documentatiebronnen. Behoud de instructies over marketing/shop/verwijzingen. Behandel een lege knowledgeBase als geen beschikbare documentatie; laat een oude cache bewust ingetrokken artikelen niet terugbrengen. De bestaande article/main-tekstextractie kan in de eerste migratie blijven. De huidige limiet van 40.000 tekens kan grote artikelen afkappen. Wijzig deze werking alleen met gerichte tests; server-HTML, heading-anchors en directe artikelantwoorden blijven compatibiliteitsvereisten. ## Ophalen, validatie en foutafhandeling 1. Maak één gedeelde ResourceCatalogService, bijvoorbeeld in ErcBasics, met een configureerbare manifest-URL waarvan bovengenoemd adres de standaard is. 2. Gebruik HTTPS en een beperkte lijst vertrouwde hosts. Begin met resources.realix-erc.com voor metadata/binaries, download.realix-erc.com voor expliciete legacyfallback en de twee hierboven genoemde exacte artikelbases. Een adres uit JSON mag geen willekeurige lokale, private of andere bestemming autoriseren. 3. Gebruik bounded reads, cancellation en een timeout, bijvoorbeeld 15 seconden voor metadata. Begin met een metadatalimiet van 2 MiB per document; verhoog die later bewust indien nodig. Een Content-Length is geen vervanging voor het tellen van ontvangen bytes. Vereis de juiste JSON-structuur/content type. 4. Bewaar ETag/Last-Modified en gebruik conditionele GET. Accepteer 304 alleen wanneer al een gevalideerde cacheversie aanwezig is. De server gebruikt hercontrole voor metadata en lange caching voor onveranderlijke binaries. 5. Verifieer catalogus-bytes tegen sizeBytes/sha256 uit het manifest, na HTTP- transferdecompressie en vóór JSON-gebruik. revision heeft een andere betekenis en is niet de hash van het volledige document inclusief revision zelf. 6. Bij een hashverschil kan tussen beide requests een nieuwe publicatie zijn verschenen. Lees het manifest eenmaal opnieuw en probeer de catalogus nog eenmaal. Herhaald verschil is een fout, geen reden om de controle te negeren. 7. Bewaar de laatste volledig gevalideerde bundel atomair. Gebruik een beperkte offlinegeldigheid, bijvoorbeeld 24 uur, en toon dat gegevens uit de cache komen. Laat opstarten en lokale projectbewerking niet van netwerktoegang afhangen. Een expliciet lege catalogus is geen netwerkfout. 8. Een fout/lege response mag geen automatische installatie, verwijdering of wijziging van een project veroorzaken. Maak verouderde/fallbackgegevens herkenbaar en log alleen veilige technische details. De metadata wordt rechtstreeks met HTTP 200 geleverd. Hou automatische redirects voor metadata en AI-artikelen uit; gebruik de URLs uit het manifest. De service heeft geen browserlogin, cookie of API-key nodig. Een HTML-loginpagina is een fout en mag niet als manifest worden geïnterpreteerd. ## Bestaande software en gefaseerde implementatie De bestaande downloadhost blijft ongewijzigd. Oudere clients gebruiken nog: - https://download.realix-erc.com/templates/filelist.json en de template-ZIPs; - https://download.realix-erc.com/versioninfo/versioninfo.md; - https://download.realix-erc.com/lookupdocs/realix-erc-ai-lookup.json. Compatibele kopieën van die drie metadata-bestanden staan ook op dezelfde paden onder resources.realix-erc.com. Dit configureert bestaande clients niet om; hun vaste oude adressen blijven bestaan. Gebruik in de nieuwe client de v1- catalogi en hun file.url. De resourcekopieën van legacy template/installer/PDF- paden worden rechtstreeks bediend zonder redirects. Relevante ERC-code in het naburige project: - ErcDesigner/appsettings.json: ProjectDownloadUrl en VersionInfo:DownloadUrl. - ErcDesigner/Services/ProjectDownloadService.cs: catalogus- en ZIP-download. - ErcDesigner/Services/AISupport/Tools/AiWebsiteKnowledgeTools.cs: harde index-URL en artikel-allowlist. - ErcBasics/Versioning/VersionEvaluationService.cs en VersionMarkdownReader.cs: ophalen, versie-/compatibiliteitsevaluatie en Markdown-parsing. - Andere gebruikers van VersionEvaluationService, waaronder Game Host, moeten worden meegenomen wanneer de gedeelde implementatie verandert. Lees eerst AGENTS.md van het ERC-project. Begin met de gedeelde manifestclient en fixturetests, verbind daarna templates, AI en versie-informatie. Houd de bestaande URLs alleen als expliciete, geteste overgangsfallback; een lege nieuwe catalogus mag niet worden vervangen door een oude. Neem template-extractie, numerieke versievergelijking, onbekende compatibiliteit, timeout, 304, onjuiste hash, redirect, gewijzigde host, onbekende schemaVersion, een lege KB en offline opstarten op in de tests. Gebruik fixtures en lokale servers; geen fictieve productiepublicaties. ## Onderhoudsgrens De releases, templates en PDF-catalogi komen uit de vastgelegde publieke downloadbronnen. De v1 Designer-AI-index wordt automatisch uit de actuele, gepubliceerde D1-KB-records opgebouwd. Concepten en archief blijven uitgesloten, ook wanneer geen enkel artikel overblijft. Titel, categorieën, tags en H2-H6- koppen leveren zoektermen; bestaande synoniemen blijven standaard behouden en kunnen in kennisbankbeheer per artikel worden aangepast. De bronservice controleert de beschermde D1-bron elke minuut en publiceert een nieuwe index en manifest atomair na verificatie van de publieke artikelen. Een mislukte controle behoudt de vorige complete bundel en wordt geregistreerd; de volgende ronde probeert opnieuw. Zowel de Site als de synchronisatie vereisen expliciete publieke vrijgave. Hun servicecredentials zijn uitsluitend server-side. Nieuwe ERC-software heeft voor manifest, index of artikelen geen token nodig. De oude downloadhost en zijn index blijven de bestaande WordPress-URLs gebruiken tot de afzonderlijke apex-/downloadmigratie. Ook de legacy-indexkopie op resources blijft gedurende deze overgang op die oude contracten staan. Gebruik voor nieuwe software uitsluitend het manifest en de v1-index. Een D1-publicatie onder de Sites-base synchroniseert de oude index niet. De machinecontracten staan in resources/schemas.mjs, de generator in resources/model.mjs, src/designer-resources.mjs en scripts/build-resources.mjs van RealixWebsite. De vastgelegde publieke brondata en bestandshashes staan onder resources/source/.