Open ContextOCTX
v0.1中文
Docs/Create OCTX

Build and Integrate

Create OCTX

First creation, derived assets, and Release version protection.

Status: v0.1 design baseline. This document defines the behavior of initial creation, subsequent Releases, and Derived Assets.

Public Entry Point

The creation side exposes only one high-level Python entry point:

python
result = create_octx(...)

The CLI exposes only one primary command:

text
octx create <workspace> --from <markdown-dir> --name <asset-name> -o <file.octx>
octx create <workspace> --version <semver> -o <file.octx>
octx create <expanded-external-package> --derive -o <derived.octx>

Establishing the initial identity and packaging a Release are internal stages. Callers are not required to compose two separate init + pack functions. See the create_octx() API for the complete parameter list.

Initial Creation

The default --from flow:

  1. Create a new OCTX Working Directory.
  2. Copy Markdown from the source directory into knowledge/ using the same relative paths, without modifying the source files.
  3. Complete the minimum OKF/OCTX frontmatter for ordinary Concept Documents.
  4. Generate and persist the Asset UUIDv7.
  5. Generate a stable UUIDv7 for each Concept Document.
  6. Build and validate the first Release.
  7. Atomically write the .octx file.

Minimum frontmatter completion:

  • If type is missing, write the general value Document.
  • If title is missing, use the first H1 if present; otherwise use the file name.
  • If octx.document_id is missing, generate a UUIDv7.
  • Do not overwrite existing fields or values.
  • If the YAML cannot be parsed safely, report an error rather than guessing and rewriting it.
  • Do not generate document IDs for index.md or log.md.

If an ordinary Markdown source happens to contain an index.md or log.md that does not conform to the OKF navigation or log structure, create must identify it as a reserved file and require the user to rename or correct it. It must not silently treat the file as a Concept Document or rename it without permission and break links.

Creation always copies Markdown from the source directory into the workspace. It does not provide an in-place move mode and never moves, renames, or rewrites source files.

If the target already has an Asset identity, create must reuse it and must not reinitialize or overwrite the ID.

An expanded external Package has no local producer state. If its content is unchanged, create may losslessly repackage the same logical Package, but it must not use that operation to issue a new Release of the original Asset. If the content is modified or enriched, the caller must explicitly use --derive; create then generates a new Asset ID and writes the original Package tuple to asset.derived_from.

Lossless repackaging preserves unknown manifest fields byte for byte. A new Release or Derived Asset instead regenerates the OCTX manifest, Release, and file list understood by the current tool. It does not inherit unknown signatures, attestations, or file-level assertions from the source. When those fields are required, a producer that understands their semantics must declare them again.

Release Version Protection

  • Use 1.0.0 when the first Release does not specify a version.
  • The same content can rebuild the same version Package, and its Package Digest remains unchanged.
  • When content or digest-participating manifest information changes, a higher SemVer must be used.
  • The reference create tool does not provide an ordinary force option that creates the same Asset and version with a different digest.
  • The build is written to a temporary file first, and the target output is replaced atomically only after complete validation succeeds.
  • If the release output has already been written but local state remains building, the next creation still uses the version and digest in the workspace's published manifest as the immutable baseline. It must not reuse the same version to publish different content.