@kindgi/specs 0.1.4-rc.5 → 0.1.5-rc.0

package/README.md

@@ -42,7 +42,7 @@ Schemas reference each other by `$id` (e.g. `pack.schema.json` →
 | Schema | Purpose |
 |---|---|
 | `agent.schema.json` | Agent — instructions + capabilities + tools + memory, declaratively composed |
-| `audit-bundle.schema.json` | HITL audit bundle — signed export of approvals + decisions + provenance refs |
+| `audit-bundle.schema.json` | Audit bundle — the signed body of an approval's audit bundle: who decided, when, why, and the evidence |
 | `capability.schema.json` | Capability declaration — model requirements as constraints |
 | `compliance-evidence.schema.json` | Compliance evidence record emitted by the runtime |
 | `discoverable.schema.json` | Discoverable entity marker — cross-history retrieval |
@@ -57,6 +57,7 @@ Schemas reference each other by `$id` (e.g. `pack.schema.json` →
 | `policy.schema.json` | Tenant policy — access control and scope rules |
 | `provenance.schema.json` | Causal DAG — signed, portable, verifiable outside the runtime |
 | `run-event.schema.json` | Kernel run lifecycle events (SSE stream) |
+| `signed-export.schema.json` | Signed export — the envelope of every signed export (audit bundle, provenance, compliance evidence): the signed bytes, the signature, the key |
 | `tool.schema.json` | Tool definition — MCP-compatible, transport-agnostic |
 
 ## Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/specs",
-  "version": "0.1.4-rc.5",
+  "version": "0.1.5-rc.0",
   "description": "Canonical JSON Schemas (Draft 2020-12) for every Kindgi artifact kind — flow, agent, tool, capability, guardrail, policy, event, run event, memory, provenance, pack, compliance evidence, audit bundle, eval suite, discoverable entity. The wire contracts every SDK, runtime, and external tool validates against. Each schema is importable by name as `@kindgi/specs/<name>.schema.json`.",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +23,7 @@
     },
     "./*.schema.json": "./schemas/*.schema.json",
     "./examples/*.json": "./examples/*.json",
+    "./test-vectors/*": "./test-vectors/*",
     "./package.json": "./package.json"
   },
   "files": [
@@ -30,6 +31,7 @@
     "src",
     "schemas",
     "examples",
+    "test-vectors",
     "README.md",
     "type-manifest.json"
   ],

package/schemas/agent.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kindgi.com/schemas/v1/agent.schema.json",
-  "$comment": "schema-version: 1.3.0",
+  "$comment": "schema-version: 1.6.0",
   "title": "Agent",
   "description": "An agent definition. Declarative composition of instructions + capabilities + tools + memory retrieval + guardrails + conversation policy. The same definition is durable across restarts and versioned like flows — provenance references agents by (id, version).",
   "type": "object",
@@ -71,7 +71,44 @@
     "retrieval": {
       "type": "array",
       "items": { "$ref": "#/$defs/RetrievalIntent" },
-      "description": "Fact-retrieval intents run before every turn to ground the model's context."
+      "description": "Fact-retrieval intents run before every turn to ground the model's context. Each sees only what the run may (its project and org, the user it acts for, its conversation and that conversation's end user, and tenant-wide facts); retrieved facts reach the model as a labelled data block, never as instructions. Schema-version 1.4.0 adds the `same-user` scope and `memory`; 1.5.0 adds `memory.remember`; 1.6.0 adds `source: conversations` and `same-segment`."
+    },
+    "memory": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How the agent uses what it retrieves.",
+      "properties": {
+        "instructionTypes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Fact types that are instructions for this agent: a retrieved fact of one of these types that a person verified goes into the system message under 'Policies (verified)'. Default: none, every retrieved fact is data."
+        },
+        "remember": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["types", "scope"],
+          "description": "Lets the agent remember: its turns offer the built-in tool `kindgi_remember` (built-in tools are `kindgi_<verb>`; an agent can't list one in `tools`). The model picks the type, the text (up to 2,000 characters), an optional slot `key` and when it stops being true; the scope comes from here and the run. Every remembered fact is `unverified`, attributed to the agent version and the call that wrote it, and expires after `keepDays` unless a person verifies it. A person approves it before any read sees it when the scope is wider than one person (`same-project`, `tenant`) or the text reads like an instruction.",
+          "properties": {
+            "types": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 },
+              "description": "The fact types it may write."
+            },
+            "scope": {
+              "type": "string",
+              "enum": ["same-user", "same-conversation", "same-project", "tenant"],
+              "description": "Where its facts go: the conversation's end user (else the user the run acts for), the conversation, the run's project, or the tenant. Each but `tenant` includes the run's project."
+            },
+            "keepDays": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3650,
+              "description": "Days an unverified fact is kept. Default 30."
+            }
+          }
+        }
+      }
     },
     "guardrails": {
       "type": "array",
@@ -207,26 +244,56 @@
     },
     "RetrievalIntent": {
       "type": "object",
-      "required": ["types", "scope"],
+      "required": ["scope"],
       "additionalProperties": false,
       "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["facts", "conversations"],
+          "description": "What it reads: facts (the default), or messages of this agent's earlier conversations, quoted in the turn's `<memory>` block as earlier conversation, never as turns. Schema-version 1.6.0."
+        },
         "types": {
           "type": "array",
           "minItems": 1,
-          "items": { "type": "string", "minLength": 1 }
+          "items": { "type": "string", "minLength": 1 },
+          "description": "The fact types it retrieves: required for facts, absent for conversations."
+        },
+        "roles": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "enum": ["user", "agent"] },
+          "description": "For conversations: whose messages it recalls. Default [\"user\"], the people's own words. Adding \"agent\" recalls the agent's earlier answers too, which can carry its mistakes: they are quoted as unverified earlier answers, and publishing warns."
         },
         "scope": {
           "type": "string",
-          "enum": ["same-conversation", "same-project", "tenant"]
+          "enum": ["same-conversation", "same-user", "same-segment", "same-project", "tenant"],
+          "description": "What the intent selects within what the run may see. Facts: this conversation's; this run's end user's and user's; the run's project's (none without a project); or every fact of the type it may see (`tenant`). Conversations: this person's other conversations with the agent (`same-user`); this conversation's messages older than the history window (`same-conversation`); conversations in the run's segment path (`same-segment`) or its project (`same-project`), whoever had them: those two quote other people's conversations. `same-segment` is for conversations only, `tenant` for facts only."
         },
         "limit": {
           "type": "integer",
           "minimum": 1,
-          "description": "Cap on facts per turn. Default 10."
+          "description": "Cap on facts (or recalled messages) per turn. Default 10."
         },
         "mode": {
           "type": "string",
-          "enum": ["keyword", "semantic", "both"]
+          "enum": ["keyword", "semantic", "both"],
+          "description": "With the user's message as the query: full-text (`keyword`), by meaning (`semantic`, which fails the turn with `semantic-unavailable` on a runtime without embeddings), or both fused by rank (without embeddings, the keyword half). Absent: the newest facts (or messages), no query."
+        }
+      },
+      "if": { "properties": { "source": { "const": "conversations" } }, "required": ["source"] },
+      "then": {
+        "properties": {
+          "types": false,
+          "scope": { "enum": ["same-user", "same-conversation", "same-segment", "same-project"] }
+        }
+      },
+      "else": {
+        "required": ["types"],
+        "properties": {
+          "types": true,
+          "roles": false,
+          "scope": { "enum": ["same-conversation", "same-user", "same-project", "tenant"] }
         }
       }
     },

package/schemas/audit-bundle.schema.json

@@ -1,173 +1,108 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kindgi.com/schemas/v1/audit-bundle.schema.json",
-  "$comment": "schema-version: 1.0.0",
-  "title": "HITL audit bundle",
-  "description": "A signed export bundling one or more HITL approvals + their decisions + references to the provenance DAGs those approvals concern. Produced by the Kindgi runtime's HITL audit export. Ed25519-signed with the same key material used for provenance signing. Verifiable outside the runtime by an external auditor with only the public key.",
+  "$comment": "schema-version: 2.0.0",
+  "title": "Audit bundle",
+  "description": "The signed body of an approval's audit bundle: what a `signed-export.schema.json` envelope of kind `audit-bundle` carries in `bundle` (decoded). Who decided a human review, when, why, and the evidence, signed by the deployment. 2.0.0: this describes the bundle the API exports (one approval, a detached signature over these bytes); 1.0.0 described a multi-approval format with an inline signature that the runtime never produced.",
   "type": "object",
   "required": [
-    "id",
+    "bundleSchemaVersion",
+    "approvalId",
     "tenantId",
-    "generatedAt",
-    "approvals",
-    "decisions",
-    "provenanceRefs",
-    "signature"
+    "subjectKind",
+    "subjectRef",
+    "requiredRole",
+    "status",
+    "createdAt",
+    "decision",
+    "evidence",
+    "exportedAt"
   ],
   "additionalProperties": false,
   "properties": {
-    "id": {
+    "bundleSchemaVersion": {
+      "const": "2.0.0"
+    },
+    "approvalId": {
       "type": "string",
-      "minLength": 1,
-      "description": "Unique bundle identifier (UUID). Stable across re-reads."
+      "minLength": 1
     },
     "tenantId": {
       "type": "string",
-      "minLength": 1,
-      "description": "Sovereignty boundary. All included approvals + decisions belong to this tenant."
+      "minLength": 1
     },
-    "generatedAt": {
+    "subjectKind": {
       "type": "string",
-      "format": "date-time",
-      "description": "ISO 8601 UTC timestamp when the bundle was materialized."
+      "description": "What the review was of: `tool-call:pending`, a session gate, a deployment…"
     },
-    "approvals": {
-      "type": "array",
-      "description": "The approval records included in this bundle. Ordering is not guaranteed; consumers must key by `id`.",
-      "items": { "$ref": "#/$defs/approval" }
+    "subjectRef": {
+      "type": "object",
+      "description": "The reviewed thing's own reference, by subject kind."
     },
-    "decisions": {
-      "type": "array",
-      "description": "The decision records for approvals in this bundle. Some approvals may not yet have a decision (bundle exported mid-flight); a consumer joins by `approvalId`.",
-      "items": { "$ref": "#/$defs/reviewDecision" }
+    "requiredRole": {
+      "enum": ["standard", "senior", "admin"]
     },
-    "provenanceRefs": {
-      "type": "array",
-      "description": "Back-references to the provenance DAGs the approvals concern. Only present when an approval carried a `provenanceRef`. Consumers fetch the DAGs from the provenance API separately — they are NOT embedded here to keep bundles small.",
-      "items": {
-        "type": "object",
-        "required": ["runId"],
-        "additionalProperties": false,
-        "properties": {
-          "runId": { "type": "string", "minLength": 1 },
-          "provenanceId": { "type": "string", "minLength": 1 }
-        }
-      }
+    "status": {
+      "enum": ["approved", "rejected", "escalated", "expired", "withdrawn"],
+      "description": "Only a decided approval is exported."
     },
-    "signature": {
-      "$ref": "#/$defs/signature"
-    }
-  },
-  "$defs": {
-    "approval": {
-      "type": "object",
-      "required": [
-        "id",
-        "tenantId",
-        "subjectKind",
-        "subjectRef",
-        "requiredRole",
-        "status",
-        "createdAt",
-        "updatedAt"
-      ],
-      "additionalProperties": false,
-      "properties": {
-        "id": { "type": "string", "minLength": 1 },
-        "tenantId": { "type": "string", "minLength": 1 },
-        "projectId": { "type": "string", "minLength": 1 },
-        "subjectKind": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Free-form kind identifier (e.g. 'agent-turn:session-hitl-gate', 'supervisor:fix-proposal', 'pack:install'). Callers namespace their kinds."
-        },
-        "subjectRef": {
-          "type": "object",
-          "description": "Polymorphic payload describing what needs approval. Shape depends on `subjectKind`.",
-          "additionalProperties": true
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "decidedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "decision": {
+      "description": "The recorded decision; `null` when the approval ended without one (expired).",
+      "oneOf": [
+        {
+          "type": "null"
         },
-        "requiredRole": { "$ref": "#/$defs/reviewerRole" },
-        "status": { "$ref": "#/$defs/approvalStatus" },
-        "assignedTo": { "type": "string", "minLength": 1 },
-        "batchKey": { "type": "string" },
-        "title": { "type": "string" },
-        "description": { "type": "string" },
-        "context": { "type": "object", "additionalProperties": true },
-        "provenanceRef": {
+        {
           "type": "object",
-          "required": ["runId"],
+          "required": ["kind", "reviewerId", "reviewerRoleAtDecision", "decidedAt"],
           "additionalProperties": false,
           "properties": {
-            "runId": { "type": "string", "minLength": 1 },
-            "provenanceId": { "type": "string", "minLength": 1 }
+            "kind": {
+              "type": "string",
+              "description": "`approve`, `reject`, `escalate` or `withdraw`."
+            },
+            "reviewerId": {
+              "type": "string"
+            },
+            "reviewerRoleAtDecision": {
+              "enum": ["standard", "senior", "admin"]
+            },
+            "decidedAt": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "rationale": {
+              "type": "string"
+            }
           }
-        },
-        "waitTokenId": { "type": "string" },
-        "createdAt": { "type": "string", "format": "date-time" },
-        "updatedAt": { "type": "string", "format": "date-time" },
-        "decidedAt": { "type": "string", "format": "date-time" },
-        "expiresAt": { "type": "string", "format": "date-time" }
-      }
+        }
+      ]
     },
-    "reviewDecision": {
+    "evidence": {
       "type": "object",
-      "required": [
-        "id",
-        "tenantId",
-        "approvalId",
-        "reviewerId",
-        "decision",
-        "reviewerRoleAtDecision",
-        "decidedAt"
-      ],
       "additionalProperties": false,
       "properties": {
-        "id": { "type": "string", "minLength": 1 },
-        "tenantId": { "type": "string", "minLength": 1 },
-        "approvalId": { "type": "string", "minLength": 1 },
-        "reviewerId": { "type": "string", "minLength": 1 },
-        "decision": {
-          "type": "string",
-          "enum": ["approve", "reject", "escalate", "withdraw"]
+        "guardrailResults": {
+          "type": "array",
+          "description": "The guardrail results that raised the review, when it came from one."
         },
-        "rationale": { "type": "string" },
-        "evidence": { "type": "object", "additionalProperties": true },
-        "reviewerRoleAtDecision": {
-          "$ref": "#/$defs/reviewerRole",
-          "description": "Snapshot of the reviewer's role at the moment of decision. A subsequent role rotation does not rewrite this audit record."
-        },
-        "decidedAt": { "type": "string", "format": "date-time" }
+        "messages": {
+          "type": "array",
+          "description": "The conversation messages of the approval's run, when asked for (`includeMessages`)."
+        }
       }
     },
-    "reviewerRole": {
-      "type": "string",
-      "enum": ["standard", "senior", "admin"],
-      "description": "Reviewer role class. Ordered by escalation authority: standard < senior < admin. `requiredRole` on an approval is the minimum; a higher-ranked reviewer can always decide a lower-tier approval."
-    },
-    "approvalStatus": {
+    "exportedAt": {
       "type": "string",
-      "enum": [
-        "pending",
-        "assigned",
-        "in_review",
-        "approved",
-        "rejected",
-        "escalated",
-        "expired",
-        "withdrawn"
-      ]
-    },
-    "signature": {
-      "type": "object",
-      "required": ["algorithm", "keyId", "value", "signedAt"],
-      "additionalProperties": false,
-      "description": "Ed25519 signature over the canonical JSON projection of the bundle (all fields except this signature). Same algorithm and canonicalization as signed provenance exports.",
-      "properties": {
-        "algorithm": { "type": "string", "enum": ["ed25519"] },
-        "keyId": { "type": "string", "minLength": 1 },
-        "value": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$" },
-        "signedAt": { "type": "string", "format": "date-time" }
-      }
+      "format": "date-time"
     }
   }
 }

package/schemas/compliance-evidence.schema.json

@@ -58,7 +58,16 @@
         "agent-promotion-refused",
         "agent-rollback",
         "agent-live-unpinned",
-        "agent-live-pin-inactive"
+        "agent-live-pin-inactive",
+        "api-key-minted",
+        "api-key-revoked",
+        "service-account-created",
+        "service-account-granted",
+        "service-account-ungranted",
+        "service-account-unregistered",
+        "person-added",
+        "person-granted",
+        "person-ungranted"
       ]
     },
     "timestamp": {

package/schemas/guardrail.schema.json

@@ -37,6 +37,10 @@
       "additionalProperties": true,
       "description": "Check-specific configuration. Interpreted by the check implementation."
     },
+    "configSchema": {
+      "type": "object",
+      "description": "JSON Schema (Draft 2020-12) of the check's config, for a check that is pack code: the pack index's `configSchema`, which a deployment keeps on the guardrails it registers. The runtime checks a guardrail's `config` against it at registration, for any guardrail naming that check, and the pack service checks it on every call. Optional; a runtime-declaration field like `codeArtifactRef`."
+    },
     "action": {
       "$ref": "#/$defs/Action"
     },

package/schemas/pack-index.schema.json

@@ -244,6 +244,7 @@
           }
         },
         "retrieval": { "type": "array" },
+        "memory": { "$ref": "#/$defs/openObject" },
         "guardrails": { "type": "array", "items": { "type": "string" } },
         "budget": { "$ref": "#/$defs/openObject" },
         "parameters": { "type": "array" },

package/schemas/pack-protocol.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kindgi.com/schemas/v1/pack-protocol.schema.json",
-  "$comment": "schema-version: 2.4.1",
+  "$comment": "schema-version: 2.5.0",
   "title": "Pack protocol",
   "description": "Pack protocol v2 — the messages a runtime exchanges with a pack service to run pack code (tool handlers and guardrail checks). One request, one response. Transport (HTTP): `POST /v1/invoke` takes a request and answers 200 with a response; `GET /v1/info` (token) answers `info`; `GET /healthz` (no token) answers 200 while the process is up; `GET /readyz` (no token) answers 200 once every module the index names has loaded and the service isn't draining. Headers: `kindgi-pack-token` (required on `/v1/invoke` and `/v1/info`; `Authorization` is deliberately not used, since platforms like Cloud Run put their own identity token there), `kindgi-timeout-ms` (relative deadline; default 120000), `kindgi-run-id`, `kindgi-request-id`, `kindgi-protocol`, `traceparent` (W3C Trace Context: the run's trace, so a pack service's records can carry its trace id; optional, protocol 2.4.1); the answer to an invoke carries `kindgi-duration-ms` and `kindgi-artifact-version`. Every outcome of running pack code is a response message with status 200 — a validation failure, a throw, an unknown tool, `deadline-exceeded`, `cancelled` (the caller closed the connection). Non-2xx statuses are transport-level only: 401 (bad token), 404, 405, 413 (body over 10 MiB), 415 (not `application/json`), 503 with `Retry-After` (not ready, draining, or at the concurrency cap — the call provably did not run), 500 (the service itself failed). Process contract: a pack service reads `--index`, `--module-root` and `--host` arguments, `KINDGI_PACK_SERVICE_TOKEN`, `PORT` (`0` picks a free port) and `KINDGI_PACK_SERVICE_MAX_CONCURRENCY`; it removes `KINDGI_PACK_SERVICE_TOKEN` from its process environment before it loads pack code, which never sees it; it loads every module before listening and exits 1 with a `{\"kind\":\"boot-failed\",\"problems\":[…]}` JSON line on stderr when one fails; once listening it writes `{\"kind\":\"listening\",\"port\":N,…}` on stderr; SIGTERM drains in-flight calls (up to 8 s; `/readyz` and new invokes answer 503 meanwhile) and exits 0.",
   "oneOf": [
@@ -46,12 +46,13 @@
         },
         "env": {
           "type": "object",
-          "description": "Resolved environment values for the call (open)."
+          "additionalProperties": { "type": "string" },
+          "description": "The env values the tool declares (`needsSpec.env`), by name, resolved for this call: the project's value, else its org's, else the tenant's, in the env the runtime serves; a schema `default` when no scope sets one (protocol 2.5.0). The runtime records them with the call, so the call re-run after a wait or a retry sends the same values. Absent when the tool declares none, and from an older runtime."
         },
         "secrets": { "type": "object", "description": "Resolved secrets for the call (open)." },
         "config": {
           "type": "object",
-          "description": "Resolved configuration for the call (open)."
+          "description": "Reserved: no runtime sends it yet (open)."
         },
         "settings": {
           "type": "object",

package/schemas/signed-export.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/signed-export.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "Signed export",
+  "description": "The envelope every signed export answers: an approval's audit bundle (`POST /v1/approvals/{approvalId}/audit-bundle`), a run's provenance (`POST /v1/provenance/{runId}/export`) and compliance evidence (`POST /v1/compliance/evidence/export`). `bundle` is base64 of the exact bytes that were signed: the body, as sorted-key JSON with no whitespace. A verifier checks the Ed25519 `signature` over those bytes and re-serializes nothing. The embedded `publicKey` only proves the bytes weren't changed; pin the deployment's keys (`GET /v1/export-signing-keys`) to know who signed them. The body of an audit bundle is `audit-bundle.schema.json`.",
+  "type": "object",
+  "required": [
+    "bundle",
+    "bundleSchemaVersion",
+    "algorithm",
+    "signingKeyId",
+    "signature",
+    "publicKey",
+    "canonicalization",
+    "exportedAt"
+  ],
+  "properties": {
+    "kind": {
+      "enum": ["audit-bundle", "provenance", "compliance"],
+      "description": "Which export this is. Absent from older servers."
+    },
+    "approvalId": {
+      "type": "string",
+      "description": "An audit bundle's approval."
+    },
+    "runId": {
+      "type": "string",
+      "description": "A provenance export's run."
+    },
+    "tenantId": {
+      "type": "string",
+      "description": "A compliance export's tenant."
+    },
+    "bundle": {
+      "type": "string",
+      "contentEncoding": "base64",
+      "contentMediaType": "application/json",
+      "description": "Base64 of the signed bytes: the body, as sorted-key JSON."
+    },
+    "bundleSchemaVersion": {
+      "type": "string",
+      "description": "The body's version, semver: audit bundle 2.0.0, provenance 1.2.0, compliance 1.0.0."
+    },
+    "algorithm": {
+      "enum": ["ed25519", "ecdsa-p256-sha256"],
+      "description": "The signing key's algorithm. An `ecdsa-p256-sha256` signature is IEEE P1363 `r‖s`. A verifier refuses an algorithm it doesn't know, naming it."
+    },
+    "signingKeyId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The key that signed it: one of `GET /v1/export-signing-keys`."
+    },
+    "signature": {
+      "type": "string",
+      "contentEncoding": "base64",
+      "description": "Base64 of the 64-byte signature over the `bundle` bytes: Ed25519's, or ECDSA P-256's as IEEE P1363 `r‖s`."
+    },
+    "publicKey": {
+      "type": "string",
+      "description": "The signing key's public half, PEM SPKI."
+    },
+    "canonicalization": {
+      "const": "sorted-key-json"
+    },
+    "exportedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When it was signed: the same instant as the signed body's `exportedAt`."
+    }
+  },
+  "additionalProperties": false
+}

package/test-vectors/README.md

@@ -0,0 +1,13 @@
+# Test vectors
+
+Fixed inputs and expected outcomes that every implementation replays: the TypeScript and Python clients in this repository, and any other verifier.
+
+## `signed-export/`
+
+A signed export, one file per algorithm. Each `valid` envelope must check out against its file's `publicKeyPem`. Each `tampered` envelope has one byte of its `bundle` changed and must fail.
+
+- `ed25519.json` — the default algorithm, for a key in memory or a file.
+- `ecdsa-p256-sha256.json` — ECDSA P-256 with SHA-256, for a KMS without Ed25519. Its signature is IEEE P1363 `r‖s`: 64 bytes, as Web Crypto takes it. A verifier whose library takes DER converts it first.
+- `unknown-algorithm.json` — an export claiming an algorithm no verifier knows. A verifier must refuse it, naming the algorithm, and never fall back to another.
+
+The envelopes follow [`signed-export.schema.json`](../schemas/signed-export.schema.json).

package/test-vectors/signed-export/ecdsa-p256-sha256.json

@@ -0,0 +1,29 @@
+{
+  "description": "A signed export (an audit bundle) signed with ecdsa-p256-sha256. \"valid\" checks out against \"publicKeyPem\"; \"tampered\" changed one byte of the bundle and must fail.",
+  "algorithm": "ecdsa-p256-sha256",
+  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXSMY38HR/vZgqsd9R2OPPMO1DfwC\nLoEHSSlI9nVFat5K8kmrIHIaix0KlpiOQHJ4094yY968Wz7c9bsu4jeGPQ==\n-----END PUBLIC KEY-----\n",
+  "valid": {
+    "approvalId": "0b6e3c1e-2f4f-4a51-9d0e-7a1f2c3d4e5f",
+    "kind": "audit-bundle",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMGI2ZTNjMWUtMmY0Zi00YTUxLTlkMGUtN2ExZjJjM2Q0ZTVmIiwiYnVuZGxlU2NoZW1hVmVyc2lvbiI6IjIuMC4wIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wN1QxMTo1OTowMC4wMDBaIiwiZGVjaXNpb24iOiJyZWplY3QiLCJyZXZpZXdlcklkIjoicmV2LTEifSwiZXhwb3J0ZWRBdCI6IjIwMjYtMTAtMDdUMTI6MDA6MDAuMDAwWiJ9",
+    "bundleSchemaVersion": "2.0.0",
+    "algorithm": "ecdsa-p256-sha256",
+    "signingKeyId": "ex_sD1K1gmwO-S3BJxR",
+    "signature": "k2iNRtXxE31ctj0xbvRYuAmFMHVXCIWl0W+mMFLGBXXvGFnTJVSmUS5EelSTW+AQ2Lt1jzO0VWVgTyJTI5TlTQ==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXSMY38HR/vZgqsd9R2OPPMO1DfwC\nLoEHSSlI9nVFat5K8kmrIHIaix0KlpiOQHJ4094yY968Wz7c9bsu4jeGPQ==\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-07T12:00:00.000Z"
+  },
+  "tampered": {
+    "approvalId": "0b6e3c1e-2f4f-4a51-9d0e-7a1f2c3d4e5f",
+    "kind": "audit-bundle",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMGI2ZTNjMWUtMmY0Zi00YTUxLTlkMGUtN2ExZjJjM2Q0ZTVmIiwiYnVuZGxlU2NoZW1hVmVyc2lvbiI6IjIuMC4wIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wN1QxMTo1OTowMC4wMDBaIiwiZGVjaXNpb24iOiJSZWplY3QiLCJyZXZpZXdlcklkIjoicmV2LTEifSwiZXhwb3J0ZWRBdCI6IjIwMjYtMTAtMDdUMTI6MDA6MDAuMDAwWiJ9",
+    "bundleSchemaVersion": "2.0.0",
+    "algorithm": "ecdsa-p256-sha256",
+    "signingKeyId": "ex_sD1K1gmwO-S3BJxR",
+    "signature": "k2iNRtXxE31ctj0xbvRYuAmFMHVXCIWl0W+mMFLGBXXvGFnTJVSmUS5EelSTW+AQ2Lt1jzO0VWVgTyJTI5TlTQ==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXSMY38HR/vZgqsd9R2OPPMO1DfwC\nLoEHSSlI9nVFat5K8kmrIHIaix0KlpiOQHJ4094yY968Wz7c9bsu4jeGPQ==\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-07T12:00:00.000Z"
+  }
+}

package/test-vectors/signed-export/ed25519.json

@@ -0,0 +1,29 @@
+{
+  "description": "A signed export (an audit bundle) signed with ed25519. \"valid\" checks out against \"publicKeyPem\"; \"tampered\" changed one byte of the bundle and must fail.",
+  "algorithm": "ed25519",
+  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAebVWLo/mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ=\n-----END PUBLIC KEY-----\n",
+  "valid": {
+    "approvalId": "0b6e3c1e-2f4f-4a51-9d0e-7a1f2c3d4e5f",
+    "kind": "audit-bundle",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMGI2ZTNjMWUtMmY0Zi00YTUxLTlkMGUtN2ExZjJjM2Q0ZTVmIiwiYnVuZGxlU2NoZW1hVmVyc2lvbiI6IjIuMC4wIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wN1QxMTo1OTowMC4wMDBaIiwiZGVjaXNpb24iOiJyZWplY3QiLCJyZXZpZXdlcklkIjoicmV2LTEifSwiZXhwb3J0ZWRBdCI6IjIwMjYtMTAtMDdUMTI6MDA6MDAuMDAwWiJ9",
+    "bundleSchemaVersion": "2.0.0",
+    "algorithm": "ed25519",
+    "signingKeyId": "ex_ZbYGc9btiEvwHCwi",
+    "signature": "auHSr03lOnru5Z8gTEuzYRU//5p4NqoeXUTNNM4XPKqcM8PCcMjj3I6ZKByve09LRQLgFfGqpQSIgpirptTuBg==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAebVWLo/mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ=\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-07T12:00:00.000Z"
+  },
+  "tampered": {
+    "approvalId": "0b6e3c1e-2f4f-4a51-9d0e-7a1f2c3d4e5f",
+    "kind": "audit-bundle",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMGI2ZTNjMWUtMmY0Zi00YTUxLTlkMGUtN2ExZjJjM2Q0ZTVmIiwiYnVuZGxlU2NoZW1hVmVyc2lvbiI6IjIuMC4wIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wN1QxMTo1OTowMC4wMDBaIiwiZGVjaXNpb24iOiJSZWplY3QiLCJyZXZpZXdlcklkIjoicmV2LTEifSwiZXhwb3J0ZWRBdCI6IjIwMjYtMTAtMDdUMTI6MDA6MDAuMDAwWiJ9",
+    "bundleSchemaVersion": "2.0.0",
+    "algorithm": "ed25519",
+    "signingKeyId": "ex_ZbYGc9btiEvwHCwi",
+    "signature": "auHSr03lOnru5Z8gTEuzYRU//5p4NqoeXUTNNM4XPKqcM8PCcMjj3I6ZKByve09LRQLgFfGqpQSIgpirptTuBg==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAebVWLo/mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ=\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-07T12:00:00.000Z"
+  }
+}

package/test-vectors/signed-export/kindgi-0.1.4.json

@@ -0,0 +1,40 @@
+{
+  "description": "Signed exports made by Kindgi 0.1.4 (the published @kindgi/api@0.1.4, an embedder's createApp with its own signingKey; the 0.1.4 runtime itself signed none). 0.1.4's audit bundle stamped the envelope's exportedAt separately from the signed one, so about 1 in 10 came out a millisecond apart. A verifier must check all three: \"auditBundle\" (the two stamps equal), \"auditBundleStampsDiffer\" (valid, with \"note\": it reports the signed time), and \"provenance\" (1.1.0, no signed exportedAt). The leniency is for this format only: envelope bundleSchemaVersion 1 over a signed bundleVersion 1.",
+  "made": "2026-10-08, @kindgi/api@0.1.4 and @kindgi/crypto@0.1.4 from npm",
+  "algorithm": "ed25519",
+  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAkDYWwEzj1U6P8hOFpI4HAm2jzR/BXyCctqdjH8d+i8g=\n-----END PUBLIC KEY-----\n",
+  "auditBundle": {
+    "approvalId": "00000000-0000-4000-8000-0000000000d4",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGQ0IiwiYnVuZGxlVmVyc2lvbiI6MSwiY3JlYXRlZEF0IjoiMjAyNi0xMC0wMVQxMDowMDowMC4wMDBaIiwiZGVjaWRlZEF0IjoiMjAyNi0xMC0wMVQxMDowNTowMC4wMDBaIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wMVQxMDowNTowMC4wMDBaIiwia2luZCI6ImFwcHJvdmUiLCJyYXRpb25hbGUiOiJXaXRoaW4gdGhlIHJlZnVuZCBsaW1pdC4iLCJyZXZpZXdlcklkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGMzIiwicmV2aWV3ZXJSb2xlQXREZWNpc2lvbiI6InN0YW5kYXJkIn0sImV2aWRlbmNlIjp7Imd1YXJkcmFpbFJlc3VsdHMiOlt7ImlkIjoiYWNtZS5saW1pdCIsIm9rIjp0cnVlfV19LCJleHBvcnRlZEF0IjoiMjAyNi0xMC0wOFQxMzoxMjoyMS41MzRaIiwicmVxdWlyZWRSb2xlIjoic3RhbmRhcmQiLCJzdGF0dXMiOiJhcHByb3ZlZCIsInN1YmplY3RLaW5kIjoidG9vbC1jYWxsIiwic3ViamVjdFJlZiI6eyJjYWxsSWQiOiJjMSIsInRvb2xJZCI6ImFjbWUucmVmdW5kIn0sInRlbmFudElkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGExIn0=",
+    "bundleSchemaVersion": 1,
+    "algorithm": "ed25519",
+    "signingKeyId": "acme-export-key-1",
+    "signature": "tLStGUncaT7NwAiBRQVQ8rA9F/Ql6YBeAAXBD9ENbymg0LYImzW/692ZAmmBe5Tje3ve6VkexKTi7SGRAXJvDg==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAkDYWwEzj1U6P8hOFpI4HAm2jzR/BXyCctqdjH8d+i8g=\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-08T13:12:21.534Z"
+  },
+  "auditBundleStampsDiffer": {
+    "approvalId": "00000000-0000-4000-8000-0000000000d4",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGQ0IiwiYnVuZGxlVmVyc2lvbiI6MSwiY3JlYXRlZEF0IjoiMjAyNi0xMC0wMVQxMDowMDowMC4wMDBaIiwiZGVjaWRlZEF0IjoiMjAyNi0xMC0wMVQxMDowNTowMC4wMDBaIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wMVQxMDowNTowMC4wMDBaIiwia2luZCI6ImFwcHJvdmUiLCJyYXRpb25hbGUiOiJXaXRoaW4gdGhlIHJlZnVuZCBsaW1pdC4iLCJyZXZpZXdlcklkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGMzIiwicmV2aWV3ZXJSb2xlQXREZWNpc2lvbiI6InN0YW5kYXJkIn0sImV2aWRlbmNlIjp7Imd1YXJkcmFpbFJlc3VsdHMiOlt7ImlkIjoiYWNtZS5saW1pdCIsIm9rIjp0cnVlfV19LCJleHBvcnRlZEF0IjoiMjAyNi0xMC0wOFQxMzoxMjoyMS41MzJaIiwicmVxdWlyZWRSb2xlIjoic3RhbmRhcmQiLCJzdGF0dXMiOiJhcHByb3ZlZCIsInN1YmplY3RLaW5kIjoidG9vbC1jYWxsIiwic3ViamVjdFJlZiI6eyJjYWxsSWQiOiJjMSIsInRvb2xJZCI6ImFjbWUucmVmdW5kIn0sInRlbmFudElkIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMGExIn0=",
+    "bundleSchemaVersion": 1,
+    "algorithm": "ed25519",
+    "signingKeyId": "acme-export-key-1",
+    "signature": "8UGQrLv3plY8TdURP/gAUYGpv6nVBzTBndKDNbfF8jslMAg4Y3Jlr5SQ6Ab615prS5BxaJqldkrEVL3rMgsVAQ==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAkDYWwEzj1U6P8hOFpI4HAm2jzR/BXyCctqdjH8d+i8g=\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-08T13:12:21.533Z"
+  },
+  "note": "made by Kindgi 0.1.4, which stamped the envelope's exportedAt separately: the signed export time is 2026-10-08T13:12:21.532Z (the envelope says 2026-10-08T13:12:21.533Z)",
+  "provenance": {
+    "runId": "run_acme_0001",
+    "bundle": "eyJidW5kbGVTY2hlbWFWZXJzaW9uIjoiMS4xLjAiLCJjcmVhdGVkQXQiOiIyMDI2LTEwLTAxVDEwOjAwOjAwLjAwMFoiLCJkYWciOnsiZWRnZXMiOlt7ImZyb20iOiJuMSIsImtpbmQiOiJjYXVzYWwiLCJ0byI6Im4yIn1dLCJub2RlcyI6W3siaWQiOiJuMSIsImtpbmQiOiJpbnB1dCIsInRpbWVzdGFtcCI6IjIwMjYtMTAtMDFUMTA6MDA6MDAuMDAwWiJ9LHsiaWQiOiJuMiIsImtpbmQiOiJtb2RlbC1vdXRwdXQiLCJtb2RlbFZlcnNpb24iOiJhY21lLW1vZGVsIiwidGltZXN0YW1wIjoiMjAyNi0xMC0wMVQxMDowMDowMi4wMDBaIn1dfSwicHJvdmVuYW5jZUlkIjoicHJvdl9hY21lXzAwMDEiLCJydW5JZCI6InJ1bl9hY21lXzAwMDEiLCJ0ZW5hbnRJZCI6IjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDBhMSIsInZlcnNpb24iOiIxLjAuMCJ9",
+    "bundleSchemaVersion": "1.1.0",
+    "algorithm": "ed25519",
+    "signingKeyId": "acme-export-key-1",
+    "signature": "X5o+gYHP12nU4yGQo4yCazWyGIyEkjIRH2U5wS788XJf5/ZlA9FezqTzYh0Nh5Q4temPZ0ac6pwOyEldlVfFBQ==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAkDYWwEzj1U6P8hOFpI4HAm2jzR/BXyCctqdjH8d+i8g=\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-08T13:12:21.594Z"
+  }
+}

package/test-vectors/signed-export/unknown-algorithm.json

@@ -0,0 +1,17 @@
+{
+  "description": "An export claiming an algorithm no verifier knows (\"ecdsa-p384-sha384\"): a verifier must refuse it, naming the algorithm, and never fall back to another.",
+  "algorithm": "ecdsa-p384-sha384",
+  "valid": null,
+  "refused": {
+    "approvalId": "0b6e3c1e-2f4f-4a51-9d0e-7a1f2c3d4e5f",
+    "kind": "audit-bundle",
+    "bundle": "eyJhcHByb3ZhbElkIjoiMGI2ZTNjMWUtMmY0Zi00YTUxLTlkMGUtN2ExZjJjM2Q0ZTVmIiwiYnVuZGxlU2NoZW1hVmVyc2lvbiI6IjIuMC4wIiwiZGVjaXNpb24iOnsiZGVjaWRlZEF0IjoiMjAyNi0xMC0wN1QxMTo1OTowMC4wMDBaIiwiZGVjaXNpb24iOiJyZWplY3QiLCJyZXZpZXdlcklkIjoicmV2LTEifSwiZXhwb3J0ZWRBdCI6IjIwMjYtMTAtMDdUMTI6MDA6MDAuMDAwWiJ9",
+    "bundleSchemaVersion": "2.0.0",
+    "algorithm": "ecdsa-p384-sha384",
+    "signingKeyId": "ex_sD1K1gmwO-S3BJxR",
+    "signature": "k2iNRtXxE31ctj0xbvRYuAmFMHVXCIWl0W+mMFLGBXXvGFnTJVSmUS5EelSTW+AQ2Lt1jzO0VWVgTyJTI5TlTQ==",
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXSMY38HR/vZgqsd9R2OPPMO1DfwC\nLoEHSSlI9nVFat5K8kmrIHIaix0KlpiOQHJ4094yY968Wz7c9bsu4jeGPQ==\n-----END PUBLIC KEY-----\n",
+    "canonicalization": "sorted-key-json",
+    "exportedAt": "2026-10-07T12:00:00.000Z"
+  }
+}