Governance evidence: cards, dossiers and the inventory

Model risk reviews, security questionnaires and works-council consultations ask the same questions: what is this model for, what may it not be used for, how was it validated, how is it monitored and who changed it. Tessera answers them from recorded evidence. It does not write new prose about your model; it packages what the platform already recorded and says plainly where evidence is missing.

This page walks through the four pieces in the order you use them:

1. author the governance fields that only you can state;
2. export the model card pinned when the model was promoted;
3. assemble a dossier for a model or a deployment slot under a review template;
4. read the organization's model inventory.

1. Author governance fields

Intended use, limitations and usage restrictions are statements you make; the platform never derives them. Set them on a model version or on a deployment slot with a merge patch:

curl -s -X PATCH "$TESSERA_API_BASE/models/$MODEL_ID/governance" -H "authorization: Bearer $TESSERA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"intended_use": "Rank shipments for proactive delay outreach.", "usage_restrictions": ["not for carrier performance reviews"]}'

• Unknown fields are refused with 400 invalid_argument; nothing is guessed.
• An explicit null removes a field; omitted fields are left as they are.
• Every change records one governance.update audit event with the values before and after.
• Each request changes only the fields it names. If two people set the same field, the later write wins; the audit trail keeps the earlier value.
• Read them back with GET /models/{model_id}/governance, or use /slots/{slot}/governance for a slot.

Writes need the admin role (or an API key with the admin scope); reads need viewer (or read).

2. Export the pinned model card

When you promote a model (POST /models/{model_id}/bundles), Tessera assembles its model card and pins it next to the bundle: the bundle manifest records the card's location and SHA-256. The pinned card also carries the governance fields as they stood at promotion.

curl -s "$TESSERA_API_BASE/models/$MODEL_ID/card:export?format=pdf" -H "authorization: Bearer $TESSERA_API_KEY" > export.json
jq -r .content export.json | base64 --decode > model-card.pdf   # `jq -r .sha256 export.json` is its SHA-256

• format is markdown (the default) or pdf. The response is a JSON envelope: content holds the exact bytes (UTF-8 text for markdown, base64 for PDF) with byte_length, sha256 and renderer_version.
• Two exports of the same pinned card are byte-identical. Every date in the document comes from the recorded evidence, never from the clock.
• Before rendering, Tessera re-verifies the bundle manifest and the pinned card against their recorded fingerprints. Altered bytes are refused with 400 failed_precondition and a {kind, uri, expected, actual} detail.
• If the governance fields changed after promotion, the pinned card is still rendered as it was pinned, followed by a separately labelled Current governance block, and governance_updated_after_pin is true.
• A model that has not been promoted exports its current card marked UNPINNED (pinned: false). So does a model promoted before card pinning existed, or one whose card could not be assembled because its training records are incomplete. A card source that fails verification refuses the promotion itself, and an imported shared model is never promoted without its pinned card.
• The PDF embeds one font (DejaVu Sans). Text it cannot draw faithfully, such as CJK or right-to-left scripts, is refused with render_unsupported_text and the list of characters; the markdown export carries that text verbatim.
• Renders larger than 10 MiB are refused with render_too_large.
• Exports are documents for people to read, and they leave out internal evaluation details that the API returns. G1 results say whether each label met its quality bar and what to do. When an export leaves details out, its appendix says so. The card fingerprint is still the SHA-256 of the complete pinned card: the bundle manifest references it, and the json download of a dossier on the model embeds it as the model card entry, so you can check it there.

3. Assemble a dossier

A dossier packages evidence for one subject (a model version or a deployment slot) under one review template. List the templates first:

curl -s "$TESSERA_API_BASE/dossier-templates" -H "authorization: Bearer $TESSERA_API_KEY"

Template	For
sr11-7.v2	Model risk management reviews in the SR 11-7 structure.
soc-security-review.v1	Security review of a detection model (alert precision, label-free anomaly monitoring).
eu-ai-act-annex-iv.v2	Technical documentation laid out like EU AI Act Annex IV. It is a documentation template, not a conformity assessment.
works-council.v1	Intended use, suppression and purpose configuration and the protocol summary, for employee-representative consultation.

Each template is fixed catalog data with a recorded fingerprint, and each dossier records the exact {template_id, template_version, template_fingerprint} it was assembled under. A changed template ships as a new version beside the old one: sr11-7.v1 and eu-ai-act-annex-iv.v1 are still listed and accepted, so the dossiers assembled under them keep citing their exact template. Assemble new dossiers with the v2 versions.

Assemble one:

curl -s -X POST "$TESSERA_API_BASE/dossiers" -H "authorization: Bearer $TESSERA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"template_id": "sr11-7.v2", "subject": {"slot_id": "'"$SLOT_ID"'"}}'

The response lists every section with its status. Download the full document:

curl -s "$TESSERA_API_BASE/dossiers/$DOSSIER_ID:download?format=json" -H "authorization: Bearer $TESSERA_API_KEY" | jq -r .content > dossier.json

format is json (the default), markdown or pdf, in the same envelope as card exports. Like card exports, a PDF download of a dossier with text the embedded font cannot draw is refused with 400 failed_precondition and a render_unsupported_text detail that lists the characters; the json and markdown downloads carry that text verbatim (alternatives: [json, markdown]).

The markdown and pdf downloads are documents for people to read: like card exports, they leave out internal evaluation details, and a dossier assembled under sr11-7.v1 or eu-ai-act-annex-iv.v1 renders without the section that the v2 templates dropped. When a render leaves details out, it says so. The json download is always the complete dossier, which the fingerprints cover.

Since renderer version 3 (renderer_version: "3"), the markdown and pdf renders also leave out every verdict criterion that compares the model with one of the platform's internal quality safeguards, in the protocol-verdict and backtest sections alike: such a row is dropped whole, with its status, rule and reason. A verdict that lost criteria this way does not show its stored overall. It shows verdict_over_comparisons_shown instead: the overall restated over the criteria shown (pass only if every one passes, fail if any fails, otherwise incomplete; a reference-level report keeps bar_only). When no criterion is left, it shows no overall. The json download keeps every criterion and the stored overall. Dossiers are rendered when you download them, so a new render of a dossier assembled earlier reports renderer_version: "3" and can have a different sha256; the stored dossier and its fingerprint never change. The console's proof center follows the same rule for evaluations and backtests.

In the same renders a comparator you uploaded reads by one name: its declared name when the dossier carries it, otherwise "Comparator 1", "Comparator 2" and so on, numbered among the comparators the render shows. A Comparators list near the top gives each comparator's id with the name the render uses for it.

Reading a dossier

Every section either embeds evidence or says it is missing. A present section holds entries of the form {kind, source, fingerprint, content}:

• fingerprint is the canonical-JSON fingerprint of content, so you can re-verify each entry against the bytes in front of you;
• an artifact source (the pinned card, the evaluation report, the bundle manifest) also names the stored object and the fingerprint it was verified against at assembly;
• an API snapshot source names the read that served the content (for example listSlotMonitors), taken as of the dossier's created_at.

A missing section states why, for example:

Reason	Meaning
source_not_bound	This deployment has no source for the evidence.
not_backtested	The model has no settled backtest yet; detail says how many were requested and how many failed.
slot_subject_only	Monitoring and alert precision are recorded per slot; assemble the dossier for the slot that serves the model.
not_evaluated, not_deployed	The model has no evaluation report (for pre-registered verdicts: no succeeded protocol evaluation), or the slot serves no bundle.
signals_disabled	The subject's bundle does not enable behavioral signals.
no_suppression_configured	No suppression set or holdout experiment exists.
no_audit_events	No audit event names the documented model, its bundles or the slot.

Other things to know:

• Audit extract. The audit section embeds the newest 500 events of the documented model, its bundles and the slot, with total_count and truncated. A capped extract always says so.
• Label-free anomaly. When the subject's bundle enables behavioral signals, every dossier includes the label-free anomaly section (its configuration, calibration and surprise drift), even if the template does not list it.
• Pre-registered verdicts. The protocol verdict sections embed every succeeded protocol evaluation of the model, newest first: one entry per evaluation report, verified against its recorded fingerprint, with the verdict and evaluation basis copied as stored.
• Backtests. The backtesting section embeds the settled backtests of the model, newest first: one entry per backtest that succeeded and whose report is stored with its fingerprint. The entry is the report as stored (cutoffs, lead-time results per label and arm, each arm's regime, and the verdict when the protocol declares lead-time metrics), verified against its recorded fingerprint at assembly, so its own fingerprint equals the report's. A report whose bytes no longer match, or that names another backtest, project, protocol, model or engine, refuses the whole dossier. Running and failed backtests are never embedded.
• Backtest budget. The section embeds reports newest first up to 1 MiB of report JSON in total (always at least the newest), so a model with many backtests still gets its dossier. When reports are left out, a last entry (source listBacktests) says so: how many backtests settled, how many are embedded and left out, and the newest 200 left out (id, protocol, engine, time and recorded fingerprint), with truncated when there are more. Reports left out are not read, so they cannot refuse the dossier. The first report past the budget is measured from its stored object's metadata before it is read; if that object is missing or was replaced, the dossier is refused (fail closed). The newest report is always embedded, even when it alone is larger than the budget. Read any of them with GET /v1/backtests/{backtest_id}. The section covers every backtest of the model, including a slot subject's backtests of other bundles of the model; each report names its bundle_id.
• Provenance. Protocol and backtest evidence carries its provenance claim (fixture, design-partner or production) verbatim; fixture numbers are never presented as measured.
• Immutability. A dossier never changes. Assembling again creates a new dossier id. Downloads re-check the stored bytes and refuse altered ones, and repeated downloads are byte-identical.
• Size. All three formats are rendered and size-checked at assembly: a dossier whose render would exceed 10 MiB is refused before anything is stored, so a stored dossier is never too large to download.
• Privacy. A dossier holds no entity-level data: its evidence is aggregate, configuration or model artifacts, and its audit extract keeps who changed what (actor id and name) but not network details. Dossiers are kept until their project is deleted.

Dossiers embed audit events, so they need the same access as the project audit feed: the member role, or an API key with the admin scope.

4. Read the model inventory

GET /orgs/{org_id}/model-inventory lists every model version and every deployment slot in every project of the organization, exactly once, with cursor pagination:

• model rows: status, owner (who created the newest bundle, from the audit trail), gate statuses, the promotion verdict and any acknowledgement, the pinned card fingerprint and when it was last validated. Models imported from a shared checkpoint are listed too, with origin: shared_checkpoint and the status imported until they are evaluated in the project;
• slot rows: status, mode, last_activated_by (who last put a bundle into service; it is not an ownership claim), monitor summaries and the active bundle.

Facts that do not exist are left out or null, never invented. Facts whose source fails verification are withheld, but the row is still listed: facts_withheld_reason names the source (eval_report or bundle_manifest), its recorded and actual fingerprints, and the facts left out. One altered artifact never hides the rest of the inventory.

The inventory needs the organization admin role, or a custom role that grants model_inventory.list. It reads across projects, so it accepts only a console session token; project API keys are refused.

In the console

The same evidence has pages under Governance in the console sidebar:

• Model inventory (/model-inventory) shows the organization's rows. A model row, a shared-checkpoint import included, opens its card; a slot row opens the slot's Governance tab. A row in another project or environment opens through /open, which checks your access before it switches the project and environment. A fact withheld because its source failed verification reads Withheld (source failed verification), never as absent, and the row's details name that source.
• A model's card page (/models/{model_id}/card, linked from the model page) shows its governance fields, the exported card and its dossiers. The exported card opens as a document to read, with the exact text on its Source tab and the length, SHA-256 and renderer version it was checked against on its Validation tab. A card no promotion has pinned yet is marked Unpinned. Organization admins edit the fields there; a save sends only the fields you changed. The exported text and every download are checked against the length and SHA-256 the server records: text that does not match is not shown, and a file that does not match is not saved. A browser that cannot compute SHA-256 (outside HTTPS) saves nothing.
• Dossiers (/dossiers) lists the project's dossiers, filtered by template or subject in the page address. Assemble a dossier on a card or a slot's Governance tab takes that subject; the assembly page also lists the newest model versions, shared imports and slots. A dossier's page states each section's evidence and has a link to every section; Read the dossier shows the dossier as a document in the same three views.

A page your role cannot read says which role, or which custom-role permission, it needs instead of showing an error.

Approvals made by a connected application

A connected application acting for its customers can create and edit contract drafts, approve contracts and source onboarding, install domain packs, tighten the leakage policy (it can never relax it), acknowledge failed advisory gates when it bundles a model, and manage alert rules on the projects it created. The evidence records those writes as follows:

• Every *_by field and every audit actor names the application: actor kind service, id application:<application_id>. This includes a contract's approved_by, a source binding's approval.principal_id, a label's or a domain-pack install's created_by, a gate acknowledgement's acknowledged_by, and a slot activation's activated_by. No human user id is recorded for these writes.
• The application may send an opaque X-Tessera-On-Behalf-Of reference. It is recorded only as details.unverified_annotation on the audit event. Tessera does not verify it, does not resolve it to a person, and never returns it in an API response.
• The partner holds the human approval evidence: who approved, when, and on what basis. A review that needs that evidence obtains it from the partner, joining on the annotation.
• A project can require a second person for these approvals (two-person approval). The approving person is always a human session, never an application, so an application's held request waits for one of the organization's admins.

Not covered

• The EU AI Act template documents a system; it does not assess conformity.