source-cache.md

Cache de sources immuables

Propriétaires : src/scenes/cache.ts, startup.ts et browser-store.ts ; stockage Node : src/server/scene-store.ts ; démarrage servi : src/host-entry.ts.

createCachedSceneSourceProvider compose un fournisseur Canvas et SceneSourceStore. Une requête sans version découvre la révision sur Canvas. Une requête exacte utilise la capsule locale vérifiée, sans réseau ; un miss acquiert puis conserve la source publiée. Une capsule corrompue échoue explicitement sans changer de scène.

La capsule solar.scene-cache.v1 conserve les octets LSMLZ, ou LSML et assets, ainsi que le manifeste Blue complet. Chaque lecture revalide l'adresse LSML, le digest des octets source/transport, les chemins d'assets et les digests des assets adressés ou nommés transportés séparément, ainsi que la fermeture Blue. offline_ready et binding_closure_complete doivent être vrais. Modifier le LSML sans changer son adresse est refusé même si son digest d'octets est recalculé. Pour les capsules LSMLZ, les chemins nommés sûrs sont admis et un basename qui correspond à une adresse SHA-1/SHA-256 est vérifié contre ses octets; cette admission suit le lecteur de packages Vision. Les demandes exactes LSML du fournisseur local peuvent extraire ces mêmes fichiers sans changer les octets LSML, la version de scène ou le digest source. La capsule garde chaque asset LSML nommé sous un digest de transport interne, indépendant de l'identité LSML.

Le transport HTTP Canvas émet actuellement séparément uniquement les chemins assets/<sha256>.<ext> et refuse les références locales SHA-1 historiques; les réponses d'asset sont liées à la version/révision et portent l'ETag du corps. Solar exige ces headers et compare aussi le corps à l'adresse SHA-256 du chemin. Une publication contenant des assets nommés ou SHA-1 n'est pas servie par ce contrat HTTP séparé; le cache local ne constitue pas une permission pour inventer un digest ou un lien d'asset que le descriptor ne fournit pas.

FileSceneSourceStore publie une seule fois par staging/link atomique dans le même dossier. Une publication concurrente identique est idempotente ; un contenu différent refuse SOURCE_CACHE_KEY_CONFLICT et préserve la capsule acceptée. Les clés sont SHA-256(id, version, format), jamais un chemin utilisateur. Les tailles d'archive, d'assets et les expansions ZIP sont bornées.

// Hôte Node/Electron ; transférer les sources à la frontière de rendu existante.
import {
  FileSceneSourceStore,
  createCachedSceneSourceProvider,
} from "@zablab/solar/server";
const provider = createCachedSceneSourceProvider(
  canvasProvider,
  new FileSceneSourceStore(accountOwnedSourceDirectory),
);
const scene = await provider.get(sceneId, { sceneVersion, format: "lsmlz" });

Le host Solar utilise directement le fournisseur Canvas, sans synchronisation du catalogue au lancement, sans préchargement et sans store IndexedDB. Un changement de scène effectue une nouvelle acquisition de source ; seules les sources et ressources de la scène active restent disponibles pour ses mutations continues. Les adaptateurs de stockage exportés ci-dessous restent des surfaces existantes à retirer avec leurs consommateurs ; ils ne sont plus raccordés au host Solar.

BrowserSceneSourceStore partage une transaction IndexedDB entre les deux lanes, avec partition SHA-256(API, credential), 64 entrées et 512 MiB, éviction par accès. Le credential n'est pas écrit. Sa rotation ouvre une nouvelle partition, et IndexedDB dépend de l'origine du host ; cette politique conservatrice n'affirme pas un cache unifié entre origines ou tokens. L'hôte Node peut fournir le store de fichiers par identité stable lorsque l'intégration applicative sera reprise. Prism n'a pas été modifié. Le runtime ne sauvegarde jamais le LSML live muté. Le cache de rendu n'autorise pas Blue : Orion conserve son admission des capsules signées/programmes. Un manifeste valide par digest n'est pas une signature.

L'adresse source scene_version est distincte du artifact_set_digest admis par Orion. Les documents Solar natifs conservent la première et portent la seconde sous x-orion-artifact-set. Le manifeste Blue porte l'adresse source ; le catalogue Orion conserve le programme signé et les déclarations associées.

scripts/prove-cold-start-cef.py exerce FileSceneSourceStore et le catalogue Orion après arrêt complet des processus : deux nouvelles instances CEF reprennent Program/Preview, source/assets/déclarations inchangés, mutations live abandonnées. Le harnais sert le cache Node vérifié aux CEF si nécessaire. Il ne certifie pas la persistance IndexedDB entre processus. Sans --capsule, le manifeste et les signatures sont des fixtures de contrat explicitement déclarées. Avec --capsule, il consomme le résultat HTTP/SQL réellement validé et signé par le Canvas local, qui a utilisé l'identité ZabAuth et la Blue publiée via ZabGate. La clé reste locale au producteur ; ce n'est pas un déploiement Canvas distant. scripts/prove-authenticated-canvas.mjs qualifie séparément login, référence signée réelle et acquisition source LSMLZ/LSML. Le locator broker-only refuse le bearer opérateur comme prévu ; sa récupération mTLS est une preuve séparée. Voir maturité et certificat.

Tests : scene-cache.test.ts, scene-store.test.ts, startup-cache.test.ts. check:source-usage couvre les modules accessibles depuis les quatre entrées ; tsc/eslint couvrent les symboles. Cette analyse ne promet pas de détecter tous les usages externes/dynamiques.