fn_registry/cpp/functions/infra/job_cache_sha256.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, framework, params, output, notes, documentation, example

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	framework	params	output	notes	documentation	example
job_cache_sha256	function	cpp	infra	1.0.0	impure	std::string fn::cache_sha256::path_for(const std::string& root, const std::string& key, const std::string& suffix = ""); bool fn::cache_sha256::ensure_dir(const std::string& root, const std::string& key); bool fn::cache_sha256::read(const std::string& root, const std::string& key, const std::string& suffix, std::string* out); bool fn::cache_sha256::write(const std::string& root, const std::string& key, const std::string& suffix, const std::string& bytes); bool fn::cache_sha256::exists(const std::string& root, const std::string& key, const std::string& suffix)	Cache addressable con layout '<root>/<key[0:2]>/<key><suffix>'. El caller hashea (tipicamente SHA-256 hex), esta funcion gestiona path + I/O. Suffix opcional permite multiples blobs por key (.html, .md, .json). Pieza extraida del jobs system de graph_explorer (issue 0026/0027) para reuso entre apps C++ que recolectan datos online.	cache sha256 addressable jobs fs scraping pendiente-usar				false	error_go_core	string cstdio filesystem fstream sstream	false			cpp/functions/infra/job_cache_sha256.cpp		name desc root Directorio raiz del cache. Tipicamente <app_dir>/local_files/cache/. La funcion crea subdirectorios on-demand. name desc key Clave de cache. Tipicamente SHA-256 hex (64 chars) de un valor canonico (URL, hash de params). El caller calcula el hash. name desc suffix Sufijo del archivo. Permite multiples blobs por la misma key. Ejemplos: '.html', '.md', '.json'. Pasa '' si solo hay un blob por key. name desc out Buffer de salida para read(). Recibe los bytes del archivo. Devuelve false si no existia. name desc bytes Contenido a escribir en write(). Se trata como binario (no se anade newline ni se interpreta).	path_for: string con el path absoluto. ensure_dir/read/write/exists: bool true en exito; read tambien rellena out. Ningun error_type custom — fallo de fs se traduce a false (ver fstream/filesystem para detalles).	1) Pure: solo path_for. Resto impuro (toca filesystem). 2) Layout compatible con el cache que ya usan los enrichers Python de graph_explorer (`<cache_dir>/<sha[0:2]>/<sha>.{html,md}`), por lo que apps C++ pueden leer blobs escritos por subprocess Python sin migrar formato. 3) Si el caller necesita SHA-256 propio, anadir funcion separada `sha256_hex_cpp_core` (no implementada aun).	Pieza minima del refactor de issue 0065. El cache es un helper standalone que cualquier app C++ que recolecte datos online puede usar para evitar refetchear. odr_console (issue 0066) lo usa via la cache_dir que pasa al subprocess Python en stdin JSON, manteniendo compatibilidad con enrichers existentes.	#include "cpp/functions/infra/job_cache_sha256.h" #include <openssl/sha.h> // o cualquier impl SHA-256 std::string url = "https://example.com/data.json"; // Hash de la URL como key (usuario provee la impl). std::string key = sha256_hex(url); std::string root = "/path/to/app/local_files/cache"; if (!fn::cache_sha256::exists(root, key, ".json")) { std::string body = fetch_http(url); fn::cache_sha256::write(root, key, ".json", body); } std::string cached; if (fn::cache_sha256::read(root, key, ".json", &cached)) { // ... usar cached ... }

Notas

Helper de I/O addressable. No hace SHA-256 — el caller provee la key (normalmente hex). Layout <root>/<key[0:2]>/<key><suffix> es identico al que usan los enrichers de graph_explorer en sus run.py, por lo que C++ y Python pueden leer/escribir el mismo cache.

Decisiones de diseño

• Hash fuera de la funcion: separar el hashing del path-handling deja el modulo libre de dependencias criptograficas. Si una app prefiere blake3, xxhash o md5 para keys mas cortas, esta funcion sigue valiendo.
• Suffix opcional: enrichers de graph_explorer guardan dos blobs por URL (.html y .md); odr_console probablemente guarde .json/.parquet. Suffix unifica casos.
• Sin SQLite: cache es solo files. Si una app necesita metadata por entry (TTL, last-access, content-type), eso vive en operations.db o en una tabla aparte.
• Layout compatible: identico al Python cache_paths() en enrichers/fetch_webpage/run.py. C++ puede leer blobs escritos por enrichers Python y viceversa.

Que NO incluye

• No incluye SHA-256 ni ningun hash. Caller responsable.
• No incluye TTL ni eviction. Implementar fuera si se necesita.
• No incluye locking entre procesos. Si dos workers escriben la misma key concurrente, ultimo gana — para invalidacion atomica usar nombre temporal + rename.