Import and Install

Status: v0.1 design baseline. This document uses SAG to explain .octx import, upgrades, conflict handling, installation state, and local rebuilding.

Importing OCTX into SAG

Public Entry Point

result = import_octx(source, options=...)

import_octx() belongs to zleap-sag, not to the general OCTX tooling. Other knowledge systems can provide their own .octx import adapters.

Installation Plan

An ordinary valid Package is installed directly after the caller explicitly invokes import; it does not require an additional confirmation step.

The following plans require explicit confirmation:

A Release conflict in which the Asset and version are the same but the Package Digest differs.
An explicit rollback to a version lower than the currently installed version.
Discarding a declared but invalid structure layer, installing only valid Markdown, and rebuilding the structure.
Extracting readable Markdown from an invalid Package and creating a Derived Asset.

An interactive CLI may prompt the user. The Python API does not display interactive prompts and instead returns:

confirmation_required + structured installation plan

The caller executes the operation again with the corresponding explicit option.

Atomic Installation

Fully validate the input.
Establish the Asset, Release, Installation, and SAG Source mapping in isolated staging.
Write valid OCTX documents and any reusable structures and vectors.
Validate the completeness of local mappings.
Commit in one transaction or perform an atomic switch.
On failure, clean up staging and leave the existing Installation unchanged.

open_octx(), validate_octx(), and inspect never trigger these writes.

Repetition, Upgrade, Conflict, and Rollback

Input	Behavior
`package_digest` is already installed	Return idempotently; do not create a second copy of the content
New `asset_id`	Create a new Asset, Installation, and SAG Source
Same Asset, higher version	Atomically upgrade the existing Installation after the user initiates import
Same Asset, lower version	Allow only an explicit rollback
Same Asset + version + digest	Same Release; idempotent
Same Asset + version, different digest, and both Packages are valid	`release_conflict`; confirmation is required
A Package's declared digest differs from the calculated result	Integrity failure; reject installation

Conflict confirmation only switches the current Installation to the new Package. The old Package, its digest, and installation history remain preserved.

During an upgrade, preserve product configuration such as the local Source ID, display name, tags, favorites, permissions, and Agent bindings. Replace OCTX-managed Documents, Chunks, Events, Entities, relations, and vectors as a complete snapshot from the new Release.

Retention periods and storage cleanup are determined by the consumer's local policy and do not change Package identity.

Installation and Indexing Lifecycle

validated
  -> installed
  -> indexing
  -> ready
       or degraded

installed: valid OCTX documents have been installed atomically and can be browsed.
indexing: missing or incompatible structures and vectors are being generated in the background.
ready: every retrieval capability required by the current consumer is available.
degraded: some indexing operations failed; OCTX documents remain available and the operations can be retried.

A valid Package that contains only Markdown and does not declare sag-structured is normal input. A complete SAG structure can be generated locally after installation; no error confirmation is required.

Declared but invalid data is different: validation errors must be shown first, and the user must explicitly choose whether to discard that structure and rebuild it.

sag-structured is a Package Capability; ready is an Installation state. The two must not be conflated.

Local Rebuilding

Rebuilt results are attached to the Installation and are not written back to the original Package:

Invalid or missing content	Rebuild scope
Any layer of the SAG structure	chunks, events, entities, relations, and related vectors
A vectors target	The complete corresponding target

An invalid SAG structure is not patched record by record, and old and new extraction results are not mixed. If vectors are invalid, only the complete corresponding target is rebuilt.

An invalid OCTX format must not be installed as the original Asset. A user may explicitly extract readable Markdown and create a Derived Asset with new Asset and document identities.