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.