Open and Validate

Status: v0.1 design baseline. This document describes safe OCTX reading, complete validation, and structured error reports.

open_octx()

package = open_octx(source)

Responsibilities:

• Open a .octx file or OCTX Working Directory.
• Perform container, path, and basic resource-safety checks.
• Parse the manifest.
• Return a read-only Package Reader.
• Stream over Documents, JSONL records, relations, and vectors.

open_octx() does not write to a database and does not indicate that every schema, digest, and relation has passed complete validation. See the open_octx() API for the complete interface.

validate_octx()

report = validate_octx(package_or_source)

Responsibilities:

• Validate the OCTX format and version.
• Validate canonical paths, the file list, and per-file SHA-256 values.
• Recalculate the Package Digest.
• Validate JSON Schema and Arrow schema.
• Validate ID uniqueness, references, relations, and hierarchy.
• Report the validity of the OCTX format and Capabilities separately.
• Produce a structured issue list.

Every import implementation must ensure successful validation within its own transaction. It must not trust that the caller previously ran validate. See the validate_octx() API for the complete interface.

Error Reports

Ordinary schema and relation issues should be returned together whenever possible. Each issue contains at least:

{
  "code": "OCTX_EVENT_MISSING_CONTENT",
  "severity": "error",
  "path": "data/events.jsonl",
  "line": 18,
  "record_id": "optional-uuid",
  "message": "event.content is required"
}

line and record_id appear only when applicable. Implementations may set a limit on the number of ordinary errors.

The following issues immediately stop further reading of the related suspicious content:

• Path traversal or destination escape.
• Links, special files, or encrypted entries.
• Entry count, size, or compression-ratio limits exceeded.
• File digest or Package Digest mismatch.

Integrity errors cannot be bypassed by user confirmation.