Metadata-Version: 2.4
Name: cf-bootstrap-core
Version: 0.1.10
Summary: Pure canonical Cogniflow bootstrap lifecycle and instance-plan model.
Author: Cogniflow Maintainers
License: GPL-3
Requires-Python: >=3.11
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# cf-bootstrap-core

`cf_bootstrap_core` is a pure, standard-library-only model for the deterministic bootstrap plan. It validates versioned requests and returns a canonical plan without creating files, directories, locks, environments, manifests, or runtime state.

## Boundary

A bootstrap plan is intended lifecycle data before side effects: identity, caller-supplied Cogniflow home context, external installation root, artifact source, and the ordered stages `validate-inputs`, `select-artifact-source`, `prepare-installation`, `install-artifacts`, `verify-installation`, and `handoff-to-service`. The handoff is ordinally explicit and is the end of imperative bootstrap responsibility. Stage names describe future work only; this package does not perform it.

A runtime manifest is operational state owned solely by `cf_runtime`. This package never creates or interprets one, writes beneath `.cogniflow`, duplicates `CogniflowHome` or `RuntimePaths`, or derives the internal `.cogniflow` layout. The installation root is an explicit external location and is not created during planning. Paths are validated lexically without filesystem access; `.` segments are normalized by `PurePath`, while `..` segments are rejected before component-aware containment, so nonexistent targets remain valid and traversal cannot bypass containment.

## Identity and protocol

`instance_id` is caller-supplied ASCII text of 1-64 characters matching `[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?`. It is case-sensitive, may contain internal dots, hyphens, and underscores, and has no path or environment meaning. No random, timestamp, process, host, working-directory, or checkout-derived identity is generated.

The package-local `cf-bootstrap-core-provider` accepts `cf.bootstrap.provider.v1` JSON-RPC-shaped JSON-lines requests with method `bootstrap/plan`. Each input line produces one response line. Exit code is `0` for empty input, successful requests, schema/protocol errors, malformed JSON, and unexpected internal errors after the lines are processed. stdout contains only compact canonical JSON; diagnostics are not written to stdout. Error codes are `MALFORMED_JSON`, `INVALID_ENVELOPE`, `PROTOCOL_VERSION_UNSUPPORTED`, `UNKNOWN_OPERATION`, `SCHEMA_INVALID`, and `INTERNAL_ERROR`.

`UNKNOWN_ENVELOPE_FIELD` means an envelope contains an unrecognized field; `INVALID_ENVELOPE` means its object shape, required fields, or field types are invalid; `UNKNOWN_REQUEST_FIELD` means the plan request body contains an unrecognized field; `SCHEMA_INVALID` means the request values violate the versioned model. `MALFORMED_JSON`, `PROTOCOL_VERSION_UNSUPPORTED`, `UNKNOWN_OPERATION`, and `INTERNAL_ERROR` retain their literal meanings.

Canonical JSON is UTF-8 JSON with sorted object keys, compact separators, deterministic list order, no volatile values, and exactly one LF terminator. Only `local-repository` and `pypi` source modes are accepted. No package is built, resolved, downloaded, installed, or started.

The public `cogniflow` launcher discovers this provider through the
`cogniflow.bootstrap_providers.v1` distribution entry-point group and invokes
the matching `cf-bootstrap-core-provider` console script as an external
process. The launcher does not import this package. Artifact resolver and
frontend discovery groups are reserved as `cogniflow.artifact_resolvers.v1`
and `cogniflow.frontends.v1`; they are not implemented here.
