Contracte d’Integració de Decision Gate + Asset Core

Visió general

Aquest document és el contracte canònic, preparat per a la implementació, per integrar Decision Gate (DG) amb Asset Core (ASC). Defineix els límits, l’autoritat i la semàntica de l’evidència necessària per preservar la independència mentre es permet una superposició de gran confiança.

Intenció de disseny: DG roman un pla de control independent. ASC roman un substrat d’estat del món independent. La integració és opcional i explícita.

Límits No Negociables

• Sense acoblament de codi: DG no es vincula amb les caixes ASC ni comparteix APIs internes.
• Sense restricció de camins d’escriptura (v1): DG no ha de seure sobre els camins d’escriptura d’ASC.
• Límits de confiança tancats per defecte: Els espais de noms que falten o no autoritzats han de denegar.
• Determinisme primer: Les mateixes entrades produeixen sortides idèntiques i execucions.

Autoritat de Namespace

Font de Veritat

• Desplegaments integrats: el catàleg de l’espai de noms ASC és autoritari.
• Standalone DG deployments: DG registry is authoritative. Desplegaments DG independents: El registre DG és autoritari. Dev-permissiu és prohibit quan namespace.authority.mode = "assetcore_http".

Regles de Validació

• DG must validate namespace_id for every namespace-scoped tool call, DG ha de validar namespace_id per a cada crida d’eina amb abast de namespace, incloent les consultes d’evidència.
• Espai de noms desconegut -> fallar tancat.
• Catàleg inaccessibles -> fallar tancat.

Regles d’ID de Namespace

• DG accepta només IDs de namespace numèrics (>= 1).
• La validació de l’autoritat d’Asset Core és directa; no hi ha taula de mapeig ni traducció.

Mapeig d’Auth/RBAC

Capa d’Integració

DG no ha de processar tokens ASC ni compartir els detalls interns d’autenticació ASC. Una capa d’integració estreta verifica l’autenticació ASC i reenvia un PrincipalContext mínim:

• tenant_id
• principal_id
• rols
• policy_class
• grups

Postura per defecte

Els valors per defecte d’autenticació són conservadors: no es permet l’autoria d’escenaris ni escrits al registre a menys que s’atorgui explícitament a la matriu de mapeig.

Matriu de Mapeig (Per defecte)

La capa d’integració mapeja els rols ASC + la classe de política en una llista blanca d’eines DG. Aquest mapeig és fail-closed: els rols que falten o desconeguts no atorguen accés.

Grups d’eines DG (referència):

• Autoria: scenario_define, schemas_register
• Run operations: scenario_start, scenario_trigger, scenario_next, Executar operacions: scenario_start, scenario_trigger, scenario_next, scenario_submit, precheck
• Read-only: scenario_status, scenarios_list, schemas_list, schemas_get, providers_list, provider_contract_get, Només lectura: scenario_status, scenarios_list, schemas_list, schemas_get, providers_list, provider_contract_get, provider_check_schema_get, evidence_query, decision_gate_docs_search
• Auditoria: runpack_export, runpack_verify

Mapeig per defecte (recomanat):

Rol ASC	Restricció de classe de política	Grups d’eines DG
TenantAdmin	Cap	Autoria + Operacions d’execució + Només lectura + Auditoria
NamespaceOwner	Cap	Autoria + Operacions d’execució + Només lectura + Auditoria
NamespaceAdmin	Cap	Autoria + Operacions d’execució + Només lectura + Auditoria
NamespaceWriter	Cap	Operacions d’execució + Només lectura + Auditoria (només verificar)
NamespaceReader	Cap	Només lectura + Auditoria (només verificar)
SchemaManager	Només Scratch, Projecte	Autoria (només esquemes) + Només lectura
AgentSandbox	Només Scratch	Operacions d’execució + Només lectura
NamespaceDeleteAdmin	Cap	Només lectura

Aplicació de la classe de polítiques:

• If policy_class is prod, SchemaManager and AgentSandbox do not Si policy_class és prod, SchemaManager i AgentSandbox no concedeixen cap permís DG (ASC ja restringeix aquests rols).
• Desconegut o falta policy_class -> denegar.

Nota d’auditoria: runpack_verify és segur de permetre àmpliament; runpack_export hauria d’estar restringit a rols d’administrador/propietari llevat que s’atorgui explícitament.

Registre ACL (DG Intern)

L’accés al registre d’esquemes està imposat per una cap capa ACL interna de DG que s’executa després de la llista blanca de l’eina de capa d’integració. Això és intencionadament separat:

• El mapeig RBAC (integració) decideix quines eines són invocables.
• Registry ACL (DG) decides who may schemas_register/list/get per Registry ACL (DG) decideix qui pot schemas_register/list/get per llogater/espai de noms, utilitzant metadades de principals i classe de política.

Predeterminats d’ACL integrats:

• Llegir: NamespaceReader+ dins del namespace.
• Escriure: NamespaceAdmin/TenantAdmin només.
• SchemaManager només pot escriure quan policy_class no és de producció.

Les implementacions d’integració no han d’assumir que les llistes d’eines permeten permisos d’escriptura al registre; ambdues capes han de permetre l’operació.

Ancoratges d’Evidència (Canon ASC)

Tota l’evidència recolzada per ASC ha de incloure els següents ancoratges:

• assetcore.namespace_id
• assetcore.commit_id
• assetcore.world_seq

Actualització opcional de l’ancoratge:

• assetcore.chain_hash (quan ASC habilita el hashing de cadena)

Aquests ancoratges han de ser capturats en runpacks i utilitzats per la verificació offline.

Contracte del Proveïdor d’Evidències

Entrades Requerides

• namespace_id (DG)
• Identificador d’espai de noms (mapejat o numèric)
• Comprovar paràmetres (container_id, class_id, etc.)

Sortides requerides

• Valor o hash d’evidència
• Hash d’evidència (JSON canònic)
• Àncora d’evidència (àncora ASC establerta anteriorment)
• Tipus de contingut
• Classe de determinisme (ha de ser determinista per a lectures ASC)

Límits i Errors

• Temps d’espera estrictes; reintentar només en errors de transport.
• Temps d’espera o error del proveïdor -> Desconegut (fallada tancada).

IDs de correlació

Requisits de Fi a Fi

• DG ha de propagar l’ID de correlació del client a les consultes d’evidència d’ASC.
• DG ha d’emetre identificadors de correlació del servidor en els registres d’auditoria i en els runpacks.
• Els IDs de correlació es registren i es capturen en les transcripcions de l’eina.

Sanitització

Els IDs de correlació proporcionats pel client són insegurs i es validen estrictament a l’entrada. Els valors no vàlids són rebutjats; només els IDs sanejats es propaguen als proveïdors d’ASC. Els IDs de correlació emesos pel servidor sempre estan presents per a les pistes d’auditoria.

Verificació de Runpack

La verificació del Runpack ha de confirmar:

• Totes les entrades d’evidència ASC inclouen ancoratges requerits.
• Els valors d’ancoratge estan ben formats i coincideixen amb l’esquema esperat.
• L’opcional assetcore.chain_hash està present quan s’ha configurat com a requerit.

Fora de l’abast (v1)

• Control de la ruta d’escriptura ASC per DG.
• Creació de l’espai de noms ASC des de DG.
• Mutació d’estat ASC a través de DG.