v1.1.3: the first run, on a machine nobody prepared

The first run, on a machine nobody prepared

MetricMine's front door, demo guide, operator's manual, and preflight now carry what a stranger on macOS, Linux, or Windows x64 needs to reach a served star on the first attempt. The pipeline, the contracts, the models, and the demo content are unchanged from v1.1.2. This is a code-only release with no attached asset; make demo-fetch (uv run mm demo-fetch on Windows) fetches the v1.1.1 asset the committed manifest names, as it did at v1.1.2.

What changed:

• The README's See it run block carries the Windows block collapsed beneath the macOS and Linux block, with make doctor (uv run mm doctor) before the fetch. The sentence claiming a recording is attached to the latest release is gone; none has been since v0.2.0.
• The demo guide names git and uv with the lines that install them (the Windows line as Astral documents it, powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex", with winget beside it), PowerShell rather than Command Prompt, a short clone path with the measured reason, and no administrator rights; every platform-dependent block has its Windows twin, the Claude Desktop entry carries both config paths and the Microsoft Store note, Path B says what it additionally provisions, and the troubleshooting section names the error text Windows prints, a proxy entry, and a Windows group.
• make doctor runs before uv exists: python3 scripts/doctor.py on any Python 3.12 answers the platform, the interpreter, the trust store, and whether uv is on PATH, and reports the rest as measured after uv sync. A check that raises records its own FAIL line while the others still print. Still eight checks.
• The operator's manual, the adding-a-source walkthrough, the contributing guide, the serving spec, and the bug report form carry the Windows text beside the macOS and Linux text. The v1.1.1 notes said they did; that rung of the Windows arc did not land, and it lands here. The docs map lists every document.
• The Arc 7 exit record, owed since v1.1.1, and the Arc 8 exit record, under docs/verification/evidence/.

The one step no runner can measure is the Claude Desktop click-through on Windows (F-55). If you run this on Windows and the server appears in Claude Desktop, say so in an issue; that closes the finding.

v1.1.2: the keyless downloads carry their own CA bundle

Patch release. One fix, no data change.

F-58. The three keyless download paths (scripts/fetch_demo.py,
scripts/fetch_common.py, scripts/fetch_sample.py) called urlopen
with no SSL context, so they inherited whatever OpenSSL's default verify
paths held. A python.org framework CPython on macOS ships those paths
empty until Install Certificates.command has run, so every fetch died
with CERTIFICATE_VERIFY_FAILED before anything built. A stranger read
that as a broken project rather than a missing CA bundle on their own
interpreter.

All three now build their context through src/metricmine/tls.py, which
adds certifi's bundle to whatever the machine already trusts rather
than replacing it, so a corporate root in the OS store still verifies.

make doctor gains a trust-store check. It reports rather than gates:
the demo path carries its own bundle and runs on a bare machine, so a
failure verdict would red a machine whose demo works.

No contract, model, or config changed. This is a code-only release with
no attached asset. The demo manifest continues to name the v1.1.1
artifact, which is what this release's demo path fetches and verifies.

v1.1.1: Windows support

Windows support for the demo path

MetricMine's demo now runs on Windows x64 as it does on macOS and Linux, and a fresh Windows runner proves it on every change to the demo path (D-42). The pipeline, the contracts, the models, and the demo content are unchanged from v1.1.0; the demo artifact attached below is the same file, byte for byte.

What changed:

• uv run mm <target> is the task entry point for the demo path (doctor, demo-fetch, ingest, demo, export-demo, demo-manifest). The Makefile's targets delegate to it, so make demo on a Mac and uv run mm demo on Windows run the same code.
• .gitattributes holds every text file to LF on checkout, whatever core.autocrlf says, so the contracts' hashes and the samples' digests measure the same on every platform; captured evidence and the committed samples keep their bytes verbatim.
• The demo-windows workflow runs Path A and Path B of the demo guide on windows-latest in PowerShell 7 and Windows PowerShell 5.1, then the manifest gate and the test suite.
• scripts/serve_smoke.py proves the command the Claude Desktop config launches over stdio, on any platform, from outside the repository.
• make doctor (uv run mm doctor on Windows) knows the matrix and prints the environment lines in the running shell's form, and every hint the demo path prints (the fetch, the digest check, the exporter, the serving module's fail-closed message) names its remedy in the running platform's form.
• The README, the demo guide, the operator's manual, the contributing guide, the serving spec, and the bug report form carry the Windows text beside the macOS and Linux text.
• Also in this release since v1.1.0: Oscar, the repository's resident guide (.claude/agents/oscar.md, a read-only Claude Code subagent), and the eight recorded live proposals for the aviation family under tests/agents/fixtures/recorded/.

What was measured, and where: every Windows line was authored without a Windows machine, parse-checked with the PowerShell 7 parser before it shipped, and run on GitHub-hosted Windows runners; the demo-windows runs on the demo-path pull requests are the measurements, and the CHANGELOG's 1.1.1 section records them. The one step no runner can measure is the click-through in Claude Desktop on Windows: the entry is documented from the MCP client guide and the command it launches is proven, and finding F-55 in the findings register holds that gap open until a person confirms it.

Outside the matrix, with the reason: Windows on Arm (the dbt parser ships no Windows Arm wheel) and WSL (it is the Linux path). Fixed: uv run pytest -q after Path B no longer fails on a machine without the isolated datacontract-cli; the local lint tests skip with the reason (F-54).

The asset: demo.duckdb, the gold-only export, 108,277,760 bytes, sha256 ba2012760b9f66eea3fb1488db4dfff3c8cc19647c3d77f24b33dadd273346eb, the same bytes v1.1.0 shipped. make demo-fetch (uv run mm demo-fetch) restores and verifies it against the committed manifest. Changelog: CHANGELOG.md, the 1.1.1 section.

Correction, added after v1.1.3: the sentence above saying the operator's manual, the serving spec, and the bug report form carry the Windows text described the prepared tree, not the merged one. That rung did not land at v1.1.1; it landed with v1.1.3.

v1.1.0: the multi-source proof

v1.1.0: the multi-source proof

A second family of sources through the same pipeline: one star, one calendar, and the joins measured rather than assumed. Additive contract semantics; the fact primary key is unchanged. Decision Record 011 (D-41) states the claim and the trial; the verdict is in the register.

What is new

• The aviation family: six committed extracts (nycflights13 flights, weather, airlines, and planes at a pinned commit, January through June 2013; OurAirports airports and runways at a pinned commit), each with a README, a digest-checked fetch script, and a bronze landing through the one file connector. docs/sources.md is the register.
• Seven silver contracts and models hand-authored from the profiles they cite: six cleanup tables and two unified tables (silver_flights, silver_airport_weather), every join declared with the completeness measured at the profile and the floor an
  error-severity rule enforces.
• The engine fan-in: a list of mapping contracts in, one star out, the shared groups as unions, the conformed calendar for the whole star.
• Gold star 1.6.0: the flights and airport_weather categories, the conformed key rules, and crossCategoryJoins declaring the join the typed surfaces support (a flight's weather at its origin in its departure hour, measured 0.9994, floor 0.99, with a worked example).
• Three gates over the claims: conformed keys, declared joins re-measured through the paths their consumers take, and the aviation conservation and business-logic gate.
• The registry split: every entry keeps data (the typed declarations) apart from expert_context (what the contracts' authors wrote, carried unchanged), and list_fact_categories names each category's subject and its registry keys.
• The demo question set: seven questions (three join the two categories on the typed surfaces, three lean on joins settled in silver, one is the retail control), with the SQL that answers each on the typed surfaces and the answers measured at the committed samples, proven through the serving path.
• The multi-source scale curve in docs/scale.md, the family selectors for the proposers with eight eval fixtures scored against their human-authored contracts, and the demo artifact as a release asset under a committed digest manifest.
• docs/adding-a-source.md: the path every source took, as the path the next one takes, validated by adding a source that is not in the demo to a fresh clone.
• docs/sources-explained.md and docs/operating.md: what each demo source is, why it is here, every decision and every join with its justification, and how to read them for data of your own; and the operator's manual, with every recurring procedure, every gate and what its failure means, and a glossary.

The demo artifact

demo.duckdb is attached to this release. make demo-fetch restores it and verifies it against demo/demo.digest.json; make demo builds the same content from the committed extracts with no key and no network.

Pins

dbt-core 1.12.3, dbt-duckdb 1.11.0, duckdb 1.4.3, datacontract-cli 1.0.12 (isolated tool), mcp 1.29.x, anthropic 1.0.x. Full details in CHANGELOG.md.

MetricMine v1.0.0: the stable line begins

MetricMine v1.0.0: the stable line begins

A contract-driven medallion pipeline that runs end to end on one machine, on DuckDB, with no cluster, no cloud account for the demo, and no warehouse credential in an agent's hands. Agents propose. Humans approve. Deterministic code executes.

Try it in ten minutes. Clone, uv sync, make doctor, then either serve the committed gold artifact straight into Claude Desktop or replay the whole pipeline keyless with make demo. The walkthrough, the Claude Desktop snippet, and the troubleshooting list are in docs/demo.md. A devcontainer is included for Codespaces.

What is in the stable line. Bronze by PyAirbyte; a deterministic profiler; a human-approved ODCS cleanup contract shaping silver; a human-approved mapping contract feeding the auto-modeling engine, which emits the gold unified event star as dbt model files under an ownership manifest (12 of the 13 models on main are engine-emitted); a typed mart beside the typed view; incremental loading one config flip away; five conservation gates at error severity in CI; an MCP server serving gold and its context registry read-only, three layers deep, through one shared query module. Two narrow proposer agents, each one structured API call with governed inputs and a fail-closed validator, draft contracts that reach contracts/ only through a reviewed pull request; every approved contract records who proposed it, a person or an agent with its model and profile hash, and which person merged it.

What is measured, and what is not claimed. docs/scale.md carries the build and query curve on two stated environments. Throughput claims and production SLAs are non-goals, as are multi-tenancy, auth, billing, streaming, orchestration platforms, autonomous multi-step agents, and more than one or two source types.

The stability rule. From this tag the pipeline, the engine, the serving layer, the two proposers, and the gates change only through the decision register. Experiments live on branches or under docs/experiments/ and end in written findings.

Everything since v0.3.0 is in the changelog.

MetricMine v0.2.0: the proposer agents, gated and live

The second tagged release. v0.1.0 (August 14, 2026) shipped the serving spine: a contract-driven medallion pipeline that runs end to end on one machine, from a committed sample through bronze, contracted silver, an engine-emitted gold star, and a read-only MCP server, with no API key. v0.2.0 adds the half the thesis was waiting for: two narrow agents that draft contracts, a person who approves them by merging a pull request, and deterministic code that executes them. Twenty-six reviewed pull requests landed on main since the first tag, each recorded in the decision register (thirty-seven binding decisions) and the findings register (thirty-two measured findings), with the evidence each one cites committed beside them.

What this release contains

The agent layer (Phase 6, closed August 28). Exactly two proposer agents: the silver cleanup proposer (stances cleanup, describe, amend) and the gold mapping proposer (stances propose, amend). Each is one structured API call against its proposal schema, with a governed default model and an allow-listed override, a capped retry, and a fail-closed exit: no tools, no loops, no third agent (D-21 as amended, D-34, D-35). Drafts land in a gitignored outbox and reach contracts/ only through a reviewed pull request. The first agent-proposed contract amendment is live: the silver contract's quantity description, at v1.1.1, landed contract-first with the compiled-context refresh the freshness gate requires (D-08, D-30). The adoption path for an existing hand-written model shipped with it: the scan with its derived review queue, verify-grain, enforce-properties, the propose-queue batch driver, and docs/adoption.md. The whole phase's live proposals, across five sessions, cost under a dollar in API calls; the demo, the tests, and CI never needed a key.

The typed surface (Arc 5a, August 25). The typed projection is now also a materialized mart (engine.marts: table, view, or both, with both the default), and the serving layer names it: list_fact_categories carries the typed table, its columns, and a query hint, so an assistant reads analytics from the mart and cites provenance from the star (D-36, Amendments K and L). The served text posture is stated rather than changed: every value read through the star, its projections, and the mart is canonical lowercased text (Amendment M to D-18).

The dbt 1.12 line (Arc 1, August 28). dbt-core 1.12.3 with dbt-duckdb 1.11.0, the full gate re-proof recorded, the byte oracle and the conservation tests unchanged; dbt Core v2 stays deferred, with its parser gate measured as parse-only for a contract-enforced project (Amendment N to D-05, F-30, F-31).

The SDLC layer (Phase 8, August 29). A working-tree guard, a PreToolUse hook committed in .claude/settings.json, keeps a coding agent inside the repository and is pinned by 55 subprocess tests in CI (D-37, F-32). A /contract-review Skill checks a contract change against the review conventions, and a read-only contract-reviewer subagent preloads it. A GitHub Actions workflow lets a maintainer's comment ask Claude Code to prepare a pull request for a backlog issue, which a person opens, reviews, and merges; the first such pull request is on main.

Verified at this tag

uv run ruff check . clean; uv run pytest -m "not local" -q at 466 passed; the three contract gates green on every pull request (datacontract lint, dbt build with contracts enforced, datacontract dbt sync then test); dbt build at 109 passing nodes over 13 models and 96 data tests; row conservation held to the digit (44,721 silver rows, 44,721 fact rows); the committed demo export refreshed at Arc 5a to carry the mart.

Where things stand

One source and one fact category. The star's physical schema is fixed regardless of how many sources feed it, so a second source adds rows and a schema key rather than a schema migration; that is a design property, demonstrated at one source. The gold layer is a generic content-addressed container by design, and its three measured trade-offs are recorded where a reader will look: at transaction grain the category dimension is one-to-one with its fact (F-23), fact_hash_id is a content address rather than a row identifier (F-24), and served values are lowercased (Amendment M). The pipeline offers traceability and conservation, not observability; determinism gives reproducible, diffable models and the gates give correctness; regeneration lands as a pull request, never as an automatic update.

Versions before 1.0.0 are milestones, not stability promises. What remains before v1.0.0: the documentation and community arc (the positioning sections, contributing and security policies, a changelog), incremental loading with the scale documentation, and the stable-release work (a support matrix, a clean-checkout demo in CI, a devcontainer). The live roadmap is the Issues tab.

Try it

git clone https://github.com/metricminellc/metricmine.git && cd metricmine
uv sync
uv run python -c "from metricmine.query import GoldWarehouse; print(GoldWarehouse().list_fact_categories())"

docs/demo.md is the ten-minute walkthrough, keyless end to end. The v0.1.0 demo recording is attached to this release as well: it still shows the serving path, and the typed mart changes where an answer is read from, not what it says.

Full changes: v0.1.0...v0.2.0

MetricMine v0.1.0 — the contract-driven spine, served

MetricMine v0.1.0 — the contract-driven spine, served

The first tagged release: Phases 0 through 5 complete. Scaffold, bronze
ingestion, deterministic profiling, contracted silver, the auto-modeling
engine and the unified event star, and a read-only MCP serving layer with a
committed demo artifact. Everything runs locally, end to end, with no API
key.

What this release demonstrates

• The signature property (D-17), measured rather than asserted. Adding
  the reserved country dimension took one mapping-contract amendment
  (v1.1.0) and one regeneration: no engine change, no physical schema
  change, no gold contract amendment, and row conservation intact to the
  digit. The full narrative, with the staleness-guard and ownership-drift
  refusals captured live:
  docs/verification/signature-test.md.
• Contracts as gates, symmetric by design. The gates were broken
  deliberately in both directions with committed evidence; break-demo
  PR #45 stays closed unmerged by design, its red check permanent.
• Serving with meaning. Five read-only MCP tools over one shared query
  module. Claude Desktop answers a business question with data from the
  star and meaning from the contract registry, cited to the contract
  version that created it.
• A keyless demo. demo/demo.duckdb (~11 MB, gold schema only,
  verified content-equal by query to the built warehouse per D-33) serves
  from a fresh clone with no build step and no credentials. The README's
  ten-minute demo starts there.

The recording

Attached: the demo recorded against the walkthrough the README links
(docs/demo.md) —
top countries with the registry's meaning cited, the business read the
model produced from the star, and a lookup_record provenance round trip.

Reading the star

Two findings minted before this tag document the star's key semantics
honestly: at transaction grain the category dimension is 1:1 with its fact
by construction
(F-23),
and fact_hash_id is a measure-payload content address, never a row
identifier
(F-24).
The counting rules live in the gold spec's Reading the star section.

Toolchain at the tag

dbt-core 1.11.12 · dbt-duckdb 1.10.1 · DuckDB 1.4.3 · datacontract-cli
1.0.12 (isolated uv tool) · airbyte 0.53.x · mcp 1.29.0 (D-32 as amended;
finding F-22) · Python 3.12 · uv. Every pin is a decision-register entry.

What's next

Phase 6: the two proposer agents — one structured API call each, grounded
in the committed profiles, with human approval as the merge. First post-tag
chore arc: the dbt-core 1.12 / dbt-duckdb 1.11 upgrade with a full gate
re-proof.