Data model & realtime

Per-project export

Lets an organisation administrator take one project's data out as a single integrity-hashed file that states exactly what it omits.

BetaEngine edition 5f8ea3af

What it does

GET /admin/v1/projects/{id}/export returns the project's namespace as newline-delimited JSON read from a pinned snapshot, with a header manifest that declares what was left out and a trailer that holds a SHA-256 over the content. Authentication material is stripped. A project that holds state which cannot be rebuilt reports the export as incomplete.

How it works

The route needs a platform-plane credential for an organisation owner or administrator, or a platform super-admin. A project service key, an anonymous key or an end-user token cannot export, not even for its own project. Export is refused for a project that is being deprovisioned or has been purged. Each export is recorded in the tamper-evident admin audit log before any data leaves, and the engine is fence-checked, so a fenced engine refuses instead of exporting an empty namespace.

The file is read from a pinned snapshot, so concurrent writes cannot tear it and writers are not paused. It has four parts. The header carries the format version (2), the project id, the export time, the log position of the snapshot and the manifest. Entity lines follow, with the project prefix removed from kinds and ids and attribute keys sorted, so the bytes are canonical. System-state lines carry the project's document lineage as typed records, validated with the importer's own verifier before they are written. The trailer holds the entity count, the system-state count, the completeness flag and the SHA-256 of the header and every line before it.

Authentication material is redacted at the export boundary. One-time-code and refresh-token records are excluded entirely, and user records are exported with the password hash blanked. Other system-internal kinds are not exported as entities. Each is declared in the manifest's omitted list with its count, a stable reason and whether it is reconstructible, and complete is true exactly when nothing non-reconstructible was left out. The response repeats this as x-kynetra-export-complete, with stable reason codes in x-kynetra-export-incomplete-reasons, so a backup job cannot mistake a partial export for a full one.

To restore, the kynetra-migrate command reads the file with the ndjson source. It copies the file to a private temporary file, verifies the hash on that copy and imports from the copy, so an edit made after the check restores nothing. --expect-pid refuses a file whose project id differs, and --require-complete refuses an export that declares itself incomplete, before any write.

Where you reach it

  • HTTPGET /admin/v1/projects/{id}/export (platform-plane credential)
  • HTTPResponse headers x-kynetra-export-format-version, x-kynetra-export-complete, x-kynetra-export-incomplete-reasons
  • CLIkynetra-migrate --to engine --data-dir <dir> --project-id <id> ndjson <file> [--expect-pid <id>] [--require-complete]

Limits

  • A project with metered usage, PII classification state or an asset-registry audit ring reports itself incomplete today, because those classes are not exported and cannot be rebuilt from what is. Read the omitted list before relying on an export as a backup.
  • The hash is a checksum and not a signature. It detects corruption, splicing and relabelling under trusted custody of the file, and it does not show who produced the file. A signed export is a recorded follow-up and is not implemented.
  • The body is built in memory and capped at 1 GiB; a larger project gets a 413. True streaming export is not built.
  • An export does not include file object bytes, which are outside the log.
  • Restore applies ordinary collection rows incrementally. A failed or refused import after the first write leaves the rows it applied, so restore into an isolated target when that matters.

Evidence

  • On this siteTenancy and project isolation
  • TestsCovered in the engine repository by 22 export tests (isolation between projects, redaction of authentication material, pinned snapshot, size cap, hash coverage, declared omissions, fenced engine and store faults, a 10,000-record round trip through the importer) and 11 further tests of lineage export, completeness flags and restore, several of them through the mounted routes

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.