Cognitive-OS-Wantsong/docs/MODEL_MANAGEMENT_V0.md

Model Management V0

status: draft_callable_kernel date: 2026-06-20

Purpose

Model management exists to make models callable in real cognitive processing. It is not the product itself.

M0-M1 defines enough structure to register and call the first two models:

• qpi;
• intellectual_archaeology.

Model Status

Allowed statuses:

• seed: source material or rough idea, not callable.
• draft: model card exists but call boundary is incomplete.
• callable: usable in a manual runtime with known limits.
• core_candidate: repeatedly useful in real runs, pending milestone review.
• core_active: accepted by owner after multiple useful runs and milestone review.
• needs_rework: known boundary or quality issue blocks normal use.
• deprecated: no longer recommended for new runs.
• archived: retained only for history or reference.

M0-M1 may use only draft and callable.

Model Levels

Allowed levels:

• L0_source_material: source article, discussion, report, or note.
• L1_candidate_model: extracted candidate model, not yet callable.
• L2_callable_model: callable manually with a known input/output contract.
• L3_core_model: future state after repeated useful runs and milestone review.
• L4_long_term_core_model: future state outside v0.1.

M0-M1 may use only L1_candidate_model and L2_callable_model.

Required Model Card Fields

Each model card must state:

• model_id;
• file path;
• runtime scope;
• governance level;
• default role;
• allowed roles;
• one-sentence definition;
• call conditions;
• no-call conditions;
• input types;
• output contract;
• depth or cost controls;
• common misuses;
• reader translation requirement;
• source seed notes;
• current limits.

Registry Requirements

models/model-registry.json is the only structured registry in M0-M1.

The registry must support:

• locating the model file;
• determining default role;
• identifying whether a model can be primary, support, contrast, calibration, translation, or routing;
• avoiding over-call by cost and no-call fields;
• pairing QPI with later deep processing;
• requiring reader translation when internal output is too model-heavy.

The registry is not a full schema system.

Upgrade Rule

A model cannot be upgraded because JSON parses, docs exist, or a selector could call it.

Future upgrades require:

• real run evidence;
• owner review;
• quality review at a milestone;
• clear usefulness beyond one sample;
• explicit decision entry.

Stop Conditions

Stop model-management expansion if work starts to require:

• complete evidence matrices before the first real runtime sample;
• a full regression suite;
• full selector calibration;
• lifecycle promotion machinery;
• proof that every boundary case is covered.

Those belong later, after the runtime proves value.