Usage multi-équipe

Un projet Touba peut être porté par plusieurs équipes : plateforme, sécurité, données, métier, exploitation, recherche ou produit. Dans ce contexte, le problème n’est pas seulement d’exécuter un workflow. Il faut aussi savoir qui possède quelle partie du contrat, quelles revues sont attendues avant un profil sensible, et si ces revues existent réellement.

La responsabilité multi-équipe (TEAM-1) ajoute un artefact explicite d’ownership et de review gates. Il sert à valider une responsabilité organisationnelle avant préparation ou inspection d’un projet.

Point clé

Un fichier touba.ownership.json ne donne aucune permission runtime. Il ne crée pas de grant, de secret, de handler, de scope mémoire, de caller d’agent, de provider ou de ressource.

Il décrit qui est responsable et quelles revues sont attendues.

Quand l’utiliser

Utilisez un artefact d’ownership quand un projet Touba contient des éléments qui touchent plusieurs responsabilités :

• un tool qui appelle un système externe ;
• un secret de production ;
• une mémoire partagée ;
• un agent appelé par plusieurs stratégies ;
• un trigger qui lance une exécution automatiquement ;
• un package local partagé entre plusieurs équipes ;
• un profil prod qui exige une revue explicite.

Modèle mental

Touba sépare trois niveaux :

Niveau	Exemple	Autorité runtime
Contrat Touba	.tb, AIR, callable_by, scopes mémoire	Oui
Wiring runtime	manifest, resource bindings, run plan, lock	Oui selon l’artefact
Responsabilité équipe	owners, reviewers, review gates	Non

Cette séparation évite un piège courant : transformer une approbation organisationnelle en permission technique. Une review peut être obligatoire pour un profil prod, mais elle n’accorde jamais network, un secret ou un handler.

Fichier touba.ownership.json

Syntaxe minimale :

touba.ownership.json

{
  "ownership_schema_version": "touba-ownership-v1",
  "teams": {
    "team:platform": {
      "display_name": "Platform"
    },
    "team:security": {
      "display_name": "Security"
    }
  },
  "owners": {
    "tool:examples.search/SearchDatasets": ["team:platform"]
  },
  "review_gates": {
    "prod": {
      "requires_review_for": [
        "tool_binding",
        "required_capability",
        "required_secret"
      ],
      "reviewers": ["team:security"]
    }
  },
  "reviews": [
    {
      "review_id": "review:search/security-001",
      "profile": "prod",
      "target_ref": "tool:examples.search/SearchDatasets",
      "reviewer": "team:security",
      "decision": "approved",
      "evidence_ref": "reviews/security-001.md"
    }
  ]
}

Champs principaux

Champ	Rôle
ownership_schema_version	version de l’artefact
teams	équipes nommées qui peuvent posséder ou revoir un élément
owners	cible Touba → équipes responsables
review_gates	règles par profil, par exemple dev ou prod
reviews	décisions de revue fournies explicitement

Les références de cible doivent être des références Touba qualifiées, par exemple :

Références

tool:examples.search/SearchDatasets
agent:examples.research/Researcher
strategy:examples.research/RunDailyResearch
memory:examples.research/ResearchNotes
trigger:examples.research/DailyResearch

Préparer avec ownership

Pour vérifier un profil sensible :

Terminal

touba prepare \
  --source src/examples/search.tb \
  --ownership touba.ownership.json \
  --profile prod \
  --mode check

Résultat attendu :

• si les owners et reviews requis existent, prepare continue sa validation ;
• si une review manque, prepare refuse avec un diagnostic explicite ;
• si l’artefact contient un champ d’autorité interdit, prepare refuse ;
• aucun handler n’est lancé pendant prepare.

Pour rendre l’artefact obligatoire :

Terminal

touba prepare \
  --source src/examples/search.tb \
  --ownership touba.ownership.json \
  --require-ownership \
  --profile prod \
  --mode check

Sans --require-ownership, l’artefact reste optionnel. Avec cette option, son absence devient un refus.

Inspecter la responsabilité

Terminal

touba inspect --ownership touba.ownership.json

inspect affiche notamment :

• la version de schéma ;
• le nombre d’équipes ;
• le nombre d’owners ;
• le nombre de review gates ;
• le nombre de reviews ;
• un graphe de responsabilité lisible.

Inspection avec plusieurs artefacts :

Terminal

touba inspect \
  --air build/touba/project.air.json \
  --manifest touba.manifest.json \
  --resource-bindings touba.resources.json \
  --run-plan touba.run-plan.json \
  --ownership touba.ownership.json

Dans cette vue, Touba distingue :

• Availability graph : ce qui est déclaré ou importé ;
• Authority graph : ce qui peut accorder une autorité d’exécution ;
• Responsibility graph : owners, review gates et reviews.

Le graphe de responsabilité est affiché avec le statut not_runtime_authority.

Exemple dev/prod

Un profil dev peut être souple :

touba.ownership.json

"review_gates": {
  "dev": {
    "requires_review_for": [],
    "reviewers": []
  }
}

Un profil prod peut exiger une revue sécurité pour les éléments sensibles :

touba.ownership.json

"review_gates": {
  "prod": {
    "requires_review_for": [
      "tool_binding",
      "required_capability",
      "required_secret",
      "memory_scope",
      "trigger_activation"
    ],
    "reviewers": ["team:security"]
  }
}

Cette différence est une règle de préparation. Le runtime applique toujours ses propres artefacts : AIR, manifest, resource bindings, run plan, secrets, lock et traces.

Refus utiles

Situation	Refus attendu
--require-ownership sans fichier	ownership manquant
cible sensible sans owner	owner manquant
review requise absente	review gate manquant
reviewer non déclaré	reviewer inconnu
champ grants dans touba.ownership.json	champ d’autorité interdit
champ secrets dans touba.ownership.json	champ d’autorité interdit
mention de conformité automatique	champ sensible interdit

Ces refus sont utiles : ils empêchent de confondre responsabilité, permission et conformité.

Périmètre technique

La responsabilité multi-équipe rend l’ownership explicite, vérifiable et inspectable sans lui donner d’autorité runtime.

Le SSO, les signatures cryptographiques de review, l’horodatage légal, la CI officielle, les preuves de conformité réglementaire, les workflows d’approbation distribués, la synchronisation avec les outils de tickets, la modification automatique du manifest et le statut Verified / Unverified relèvent de couches organisationnelles et plateforme séparées.