Marivo 0.3.2

Marivo 0.3.2 is an atomic breaking cutover of the analysis surface. The help system, artifact contract, error model, boundary model, packaged skill, and CLI route all change together. Removed surfaces have no aliases, redirects, deprecated fields, dual-read paths, or compatibility flags. The additive frame.id == frame.ref identity alias does not restore a removed API.

Highlights

A closed capability kernel replaces the old topic-based help surface. Every public operator, constructor, read, recovery, and boundary crossing is registered with a stable capability_id, accepted_inputs, and output_family. The CLI route marivo help analysis [target] (or python -m marivo help analysis [target]) prints a fingerprinted capability index; mv.help() and mv.help(target) provide the same surface from Python. A runtime family gate validates submitted inputs against the registry’s accepted_inputs before any backend work begins.
ArtifactAffordance.operator is replaced by capability_id, public_entrypoint, help_target, and expected_output_family. Each affordance is a mechanical compatibility gate derived from the capability registry, not a recommendation.
ArtifactContract now carries boundary_ports: typed ArtifactBoundaryPort objects describing terminal-exit ports (e.g. boundary.to_pandas) with preserves and does_not_preserve guarantees.
Tier-1 mean metrics now persist exact sum(measure) and count_non_null(measure) components during observe, enabling direct weighted-mix attribution without changing the semantic model.
Attribution now computes exact one-sided contributions for new and churned component segments and fails closed unless every deepest partition reconciles to its independently computed total delta. AttributionFrame.show() renders total, one-sided, unattributed, and residual reconciliation facts.
Analysis inspection is more uniform: live sessions implement bounded render() / show(), every frame and frame summary exposes .id as a read-only alias of .ref, catalog help labels collections as properties, and mv.help("AttributionMode") distinguishes multi-axis row layout from attribution math.
Artifact help now teaches progressive reads in a stable order: show() for bounded state, contract() for mechanical compatibility, then to_pandas() only when the remaining work is intentionally custom and terminal.
DeltaFrame.show() now exposes the persisted attribution gate, and grouping help topics render as mv.help("...") with their real members instead of advertising nonexistent session.recovery or session.artifacts namespaces.
The generic AnalysisError.details bag is replaced by stable typed fields: expected, received, location, and repair. The repair field is a typed AnalysisRepair object with kind, action, help_target, optional snippet, and optional candidates drawn from live state.
BaseFrame.describe() and BaseFrame.plot() are removed. Accessing them raises AttributeError. Use frame.show() for bounded inspection and frame.to_pandas() for terminal custom analysis.
The marivo-analysis skill is now a one-file boundary kernel. It owns hard boundaries, handoffs, evidence continuity, and closeout obligations. It does not duplicate API signatures, operator inventory, call examples, ordered process, methodology checklists, or report templates. The references/ attachment tree is deleted.
session.observe(...) is the sole canonical MetricFrame producer. derive_metric_frame, escape_hatch, and all promotion paths (promote_metric_frame, promote_delta_frame, promote_attribution_frame, from_pandas, explore_ibis) are removed. Arbitrary Ibis, pandas, or SQL data can no longer be upgraded into canonical analysis artifacts.
md.raw_sql(...) is the sole terminal raw SQL execution path. It composes authoring_timeout with a read-only transaction, detects exact row truncation, and exposes RawSqlResult.to_pandas() for terminal pandas export. Terminal results cannot re-enter typed analysis.
mv.session.recent(...) and mv.session.inspect(name) provide bounded, newest-first historical-session reference without resuming or touching the inspected session. Semantic gaps now stop only the affected typed branch; terminal raw SQL may continue with disclosed temporary inferred semantics, while durable semantic authoring remains closeout-approval gated.

Breaking changes

Evidence Engine Cutover A. The former finding -> proposition -> assessment judgment runtime is replaced by deterministic typed findings and one bounded ArtifactDigest per artifact. session.knowledge(), proposition/assessment reads, persisted follow-ups, open items, next steps, and their public types are removed without aliases. Marivo no longer emits generic validation/confidence labels or session-level judgments; the agent owns cross-artifact synthesis and planning.
One artifact evidence path. Use artifact.evidence_status, artifact.evidence_digest, and artifact.show(). evidence_summary, blocking_issues, ConfidenceScope, and the artifact issue shortcut are removed. contract().issues contains the closed ArtifactIssue union, and AnalysisScope retains the existing metric-shaped scope.
Direct bounded audit reads. session.evidence.digests(...), .findings(...), .digest(ref), .finding(id), and .trace(id) replace the judgment API. List reads return immutable keyset pages. Evidence-store unavailability raises EvidenceStoreUnavailableError; it is never reported as an empty page.
Typed candidate selection. CandidateSet.select(rank=1) now returns a closed shape-specific selection. The arbitrary attribute= read and candidate affordance/constraint payloads are removed.
Role-preserving affordances. Flattened required_inputs and ArtifactParamTemplate are replaced by exact parameter requirements with accepted families and current-artifact bindability. Invocation-option enumeration is intentionally not part of this cutover.
Removed help topics. mv.help('workflow') and mv.help('advanced') no longer resolve. The new help system uses mv.help() (root index), mv.help(target) (focused capability), and mv.help(ClassName) (type help). String aliases for help targets are removed; use canonical registered targets from the live surface.
ArtifactAffordance.operator removed. Replaced by capability_id, public_entrypoint, help_target, and expected_output_family.
AnalysisError.details removed. Replaced by stable typed fields (expected, received, location, repair) with typed AnalysisRepair objects. There is no generic details bag.
ArtifactContract.boundary_ports added. Typed terminal-exit boundary ports derived from the capability registry.
pct_contribution removed. Attribution rows now expose share_of_total_delta, share_of_positive_pool, and share_of_negative_pool, so signed net shares and same-sign pool shares no longer share an implicit or incomplete denominator.
BaseFrame.describe() and BaseFrame.plot() removed. Intentional AttributeError. Use frame.show() and frame.to_pandas().
marivo-analysis skill reduced to one file. The references/ tree is deleted. The skill is a boundary protocol, not a manual.
New CLI route and fingerprint. marivo help analysis [target] prints the Marivo version, resolved Python executable, and package path as an environment fingerprint. A bare marivo resolved from PATH is not authoritative unless its fingerprint matches the analysis interpreter.
Runtime family gate. Submitted inputs are validated against the registry’s accepted_inputs before backend work. Mismatches fail closed with a structured AnalysisError.
derive_metric_frame and promotion paths removed. Session.derive_metric_frame(...), escape_hatch.explore_ibis(...), escape_hatch.from_pandas(...), escape_hatch.promote_metric_frame(...), escape_hatch.promote_delta_frame(...), escape_hatch.promote_attribution_frame(...), IbisQuerySpec, MetricColumns, ibis_query, metric_columns, time_column, dimension_column, PromotionPolicy, PromotionSemanticAnchors, PromotionFailedError, and ExplorationResult are removed. session.observe(...) is the sole canonical MetricFrame producer.
md.raw_sql(...) is the sole terminal raw SQL path. It enforces authoring_timeout composed with a read-only transaction, detects exact row truncation, and returns RawSqlResult with timeout_seconds, duration_ms, truncated, and to_pandas(). Terminal results cannot re-enter typed analysis.

No compatibility or migration behavior

This is an atomic cutover. Removed symbols, topics, and fields have no compatibility aliases, redirects, deprecated fields, dual-read paths, compatibility flags, or automatic migration. Code that references them must be updated to the new surface. The additive frame.id == frame.ref alias is only an identity-access convenience and does not change persisted metadata.

Analysis evidence stores are included in this rule. A non-current judgment.db and a frame sidecar containing removed evidence fields are rejected; recreate the analysis session to produce canonical typed findings and digests.

Semantic and datasource live surface

0.3.2 also folds the datasource/semantic live-surface cutover into this same atomic release. The installed package is now the single authority for datasource and semantic authoring facts, observable state, mechanically available calls, effects, and typed repair. The packaged marivo-semantic skill is reduced to a one-file boundary kernel that owns routing discipline, hard boundaries and closeout obligations; it no longer duplicates API signatures, operator inventory, call examples, or repair catalogs.

Added

Direct semantic readiness for analysis. ReadinessReport.analysis_ready_refs lists the requested refs that passed scoped certification. Blockers and warnings remain on the same report; callers handle them explicitly before using those refs through the ordinary analysis APIs. No intermediate transfer object or receipt is required.
Native datasource and semantic CLI help. marivo help semantic (and python -m marivo help semantic) is the default integrated authoring entry; marivo help datasource owns the physical stage. Both are backed by the same resolver and renderer as md.help(...) / ms.help(...). marivo --help points to these entries and to marivo help analysis; it no longer teaches python -c snippets.
Environment fingerprint on track help. Track root help (marivo help datasource, marivo help semantic, marivo help analysis) prints the Marivo version, resolved Python executable, and package path, so an agent can verify that help and execution share one interpreter before trusting any authoring guidance. The bare marivo --help points to these tracks but does not itself print the interpreter fingerprint.
Typed repair. Free-form recovery strings on mechanically actionable readiness/preview results and datasource/semantic errors are replaced by typed AuthoringRepair objects (kind, help_target, action, optional snippet, optional candidates, preserves_evidence). The advisory suggested_action on richness gaps is retained under its own advisory rule and is not consumed as a repair or transition.
Object-near .contract() on state-bearing results. The .contract() convention applies to state-bearing results like CatalogObject, VerifyResult, and ReadinessReport, exposing mechanically valid next actions (e.g. VerifyResult.contract() may expose preview, while ReadinessReport exposes certified refs directly through analysis_ready_refs). Contracts carry namespaced live help targets and complete orthogonal effect metadata (data access, connection, mutation, guards).

Removed

Duplicate top-level verification/readiness wrappers. ms.verify_object(...) and ms.readiness(...) are removed from the top-level ms surface; SemanticCatalog.verify_object(...), SemanticCatalog.preview(...), and SemanticCatalog.readiness(...) are the sole public receivers.
Prepare-era AuthoringQuestion. The public AuthoringQuestion export, its options / default_option contract, and the unused question-bearing assessment path are removed. No replacement question DTO is added; an unresolved business decision is a skill-owned one-question stop, not a runtime user_decision repair.
Free-form mechanical recovery strings. next_calls on datasource evidence/inspection results and suggested_action as a mechanically actionable readiness/preview field are removed. They are replaced by typed contracts and AuthoringRepair. (Advisory richness retains its own suggested_action.)
Packaged skill attachments/examples as runtime documentation dependencies. The references/ attachment tree and example runners are deleted. No active code, constraint, error, or latest doc links to deleted skill attachments. The installed runtime is self-explanatory from its public Python and CLI surfaces.

No compatibility or migration behavior (semantic cutover)

The semantic/datasource cutover is target-only. There are no compatibility aliases, no dual help path, no transition-string bridge, no skill-document fallback, and no migration workflow. Historical versioned documentation and release notes are unchanged. Code that references removed symbols, wrappers, or fields must be updated to the new live surface.

Documentation

Updated the analysis-workflow, first-analysis, and evidence docs in English and Chinese to route entry through the project interpreter and fingerprint, explain capability discovery, object-near help, static type algebra, artifact show/contract, structured errors, terminal boundary exits, and semantic-authoring repair.
Updated agent-guide.md and active analysis specs with the new ownership model: environment-verified live surfaces own capabilities and runtime guidance; the skill owns hard boundaries, routing, evidence continuity, and closeout obligations; the agent owns planning and judgment.
Marked both 2026-07-13 design specs as approved; implementation planned.

Installation

pip install marivo

Install the backend extra for the datasource you plan to use:

pip install "marivo[duckdb]"
pip install "marivo[mysql]"
pip install "marivo[trino]"
pip install "marivo[postgres]"
pip install "marivo[clickhouse]"
pip install "marivo[all]"

Marivo 0.3.2 requires Python 3.12 or newer.