millforge 0.1.0__py3-none-any.whl

millforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,844 @@
+Metadata-Version: 2.4
+Name: millforge
+Version: 0.1.0
+Summary: A typed Python runner and harness compiler for guarded LLM tool execution.
+Project-URL: Homepage, https://github.com/tim-osterhus/millforge
+Project-URL: Repository, https://github.com/tim-osterhus/millforge
+Author-email: Tim Osterhus <tim@millrace.ai>
+Maintainer-email: Tim Osterhus <tim@millrace.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,guardrails,llm,millforge,tool-calling
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pathspec<1,>=0.12
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Millforge
+
+A typed Python runner and harness compiler for guarded LLM tool execution.
+
+It is inspired by the principles of
+[Forge guardrails](https://github.com/antoinezambelli/forge).
+
+Millforge is currently pre-alpha. Its author and maintainer is
+Tim Osterhus <tim@millrace.ai>, and its canonical homepage and source repository
+are [github.com/tim-osterhus/millforge](https://github.com/tim-osterhus/millforge).
+
+Millforge is licensed under Apache-2.0; packaged upstream MIT notices and
+provenance records remain at `millforge/_forge/{LICENSE,PROVENANCE.json}` and
+`millforge/tools/pi_compat/{PI_LICENSE,PROVENANCE.json}`.
+
+## Forge Provenance
+
+| Field    | Value                                                                       |
+|----------|-----------------------------------------------------------------------------|
+| Name     | forge-guardrails                                                            |
+| Version  | 0.7.4                                                                       |
+| License  | MIT                                                                         |
+| Upstream | [https://github.com/antoinezambelli/forge](https://github.com/antoinezambelli/forge) |
+| Commit   | `bd99f4df0a7aab2fd4db2e6dae7f810a32617d76`                                  |
+
+Millforge is an independent project. Its public API is Millforge-owned, while
+`src/millforge/_forge/` contains a private vendored subset of the reviewed
+Forge v0.7.4 guarded-loop implementation. That subset is limited to
+transport-free protocol helpers, workflow/message/step/inference/runner
+modules, guardrails, prompt helpers, fixed context management, the private
+Millforge plan-translation adapter layer, and private model/tool/terminal
+bridge adapters, plus `ForgeGuardrailBackend` runtime integration.
+
+The vendored subset intentionally excludes provider clients, proxy/server/CLI
+modules, eval assets, dashboards, hardware discovery, `httpx`, provider SDKs,
+and transport implementation code. Runtime package code does not import or
+depend on `ref-forge/`.
+
+Machine-readable provenance lives in
+`src/millforge/_forge/PROVENANCE.json`. The upstream MIT license is retained in
+`src/millforge/_forge/LICENSE`, and update rules are documented in
+`src/millforge/_forge/UPDATE_POLICY.md`.
+
+Private behavioral patches are recorded in the manifest's
+`private_behavior_patches` section. They currently cover configurable guarded
+loop violation budgets, non-retryable tool outcomes, strict supported-subset
+JSON Schema conversion, mapped prerequisite argument enforcement, and private
+subset import safety. Runtime adapter behavior also classifies exhausted
+prerequisite correction budgets as `budget_exhausted` with diagnostic code
+`prerequisite_budget_exhausted`.
+
+## Snapshot Comparison
+
+Millforge's reference snapshot in `ref-forge/` is based on upstream
+[forge-guardrails](https://github.com/antoinezambelli/forge) tag
+[`v0.7.4`](https://github.com/antoinezambelli/forge/releases/tag/v0.7.4).
+The snapshot was taken at commit
+`bd99f4df0a7aab2fd4db2e6dae7f810a32617d76`.
+
+**Note:** The `ref-forge/` directory is a plain-file snapshot and does **not**
+contain `.git` metadata. It is provided for reference and comparison purposes
+only.
+
+## Development
+
+- Python 3.11 or newer
+- Install for development: `pip install -e ".[dev]"`
+- Run tests: `pytest`
+- Lint: `ruff check .`
+- Format: `ruff format --check .`
+
+| Runtime | Support |
+|---------|---------|
+| Linux on Python 3.11-3.13 | Supported |
+| macOS on Python 3.11-3.12 | Supported |
+| WSL | Supported through Linux |
+| Native Windows | Deferred |
+
+CPython is the gated interpreter. PyPy and other alternative interpreters are
+not currently claimed as supported.
+
+To verify the committed checkout without inherited local state, run this from
+the source repository in a POSIX shell using the provisioned development
+environment:
+
+```bash
+source_repo=$(git rev-parse --show-toplevel)
+source_commit=$(git rev-parse HEAD)
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+
+git clone --no-hardlinks "$source_repo" "$tmp_dir/millforge"
+cd "$tmp_dir/millforge"
+test "$(git rev-parse HEAD)" = "$source_commit"
+test ! -e millrace-agents
+test ! -e ideas
+test ! -e ref-forge
+test ! -e reference
+test -z "$(git status --short --untracked-files=all)"
+
+python -m pytest \
+  tests/test_connector_custom_tool_closure.py \
+  tests/test_pi_compat_operations.py \
+  tests/test_tool_registry_closure.py \
+  tests/test_forge_provenance.py
+python -m pytest -m "not live_model_backend"
+test -z "$(git status --short)"
+```
+
+## Millforge Base
+
+`millforge-base` is an unrestricted compatibility preset based on
+`@earendil-works/pi-coding-agent` 0.79.6.
+
+Runner execution is supported on Linux and macOS. WSL is supported through its
+Linux execution semantics (`sys.platform == "linux"`). Native Windows is
+unsupported and deferred: package import and argument-free
+`describe_millforge_base()` inspection remain available there, but composition,
+runner creation, and execution raise `UnsupportedPlatformError` before context
+discovery, artifact creation, model resolution, provider calls, process work,
+or tool side effects. Millforge does not claim native Windows path, shell,
+process-tree, or fixture parity.
+
+> A Python behavioral port of Pi 0.79.6's complete built-in coding tool pack, adapted to Millforge's compiler and runtime contracts.
+
+It exposes Pi-derived `read`, `bash`, `edit`, `write`, `grep`, `find`, and
+`ls` tools, plus `submit`, `block`, and `reject` terminal controls.
+
+**Security warning:** `millforge-base` is unrestricted and unsandboxed.
+
+> millforge-base runs with the permissions of the Millforge process. It can read, write, delete, execute commands, access the network, and access credentials available to that process. Use only in trusted environments.
+
+Deliberate adaptations replace Pi's Node filesystem and process APIs with
+Python APIs, use the documented Python search behavior instead of `fd`/`rg`,
+return text-only supported-image reads, translate cancellation to Millforge's
+poll/wait protocol, and resolve the host shell through the Pi-compatible
+platform policy. The machine-readable source records and adaptations are in
+`src/millforge/tools/pi_compat/PROVENANCE.json`.
+
+The Python composition API creates the validated source, compiled plan,
+Pi-compatible executor, and sanitized metadata without a provider call:
+
+```python
+from pathlib import Path
+
+from millforge import create_millforge_base_components
+
+components = create_millforge_base_components(
+    model_profile=profile,
+    cwd=Path("/absolute/workspace"),
+    cancellation_resolver=cancellation_resolver,
+)
+```
+
+The supported live OpenAI-compatible surface is
+`create_millforge_base_live_runner()`. Construction is async only so any
+factory-owned HTTP client can be cleaned up if a later local construction step
+fails; it performs no network request or provider probe. Every Millforge type
+and factory in this direct construction, execution, and asynchronous cleanup
+example is imported from the `millforge` package root:
+
+```python
+from pathlib import Path
+
+from millforge import (
+    AuthenticationPolicy,
+    AuthenticationScheme,
+    CapabilityDeclarations,
+    CapabilitySupport,
+    EndpointConfig,
+    OpenAICompatibleTimeouts,
+    RequestOptionAllowlist,
+    ResolvedModelProfile,
+    SecretRef,
+    create_millforge_base_live_runner,
+)
+
+secret_ref = SecretRef(secret_id="model-key", env_var="MODEL_API_KEY")
+profile = ResolvedModelProfile(
+    profile_id="local-tools",
+    provider_id="openai-compatible",
+    model_id="tool-model",
+    endpoint=EndpointConfig(base_url="https://models.example/v1"),
+    authentication=AuthenticationPolicy(
+        scheme=AuthenticationScheme.BEARER,
+        secret_ref=secret_ref,
+    ),
+    capabilities=CapabilityDeclarations(
+        support={
+            "tool_calls": CapabilitySupport.SUPPORTED,
+            "system_messages": CapabilitySupport.SUPPORTED,
+            "tool_result_messages": CapabilitySupport.SUPPORTED,
+        }
+    ),
+    request_options=RequestOptionAllowlist(
+        allowed_options=("parallel_tool_calls",),
+    ),
+    timeout_seconds=90,
+    source_digest="caller-profile-v1",
+)
+
+live_runner = await create_millforge_base_live_runner(
+    profile_id="local-tools",
+    model_profile=profile,
+    secret_ref=secret_ref,
+    secret_resolver=secret_resolver,
+    cwd=Path("/absolute/workspace"),
+    clock=clock,
+    cancellation_resolver=cancellation_resolver,
+    artifact_writer_factory=artifact_writer_factory,
+    timeouts=OpenAICompatibleTimeouts(
+        connect_seconds=10,
+        read_seconds=90,
+        write_seconds=30,
+        pool_seconds=10,
+        local_total_seconds=75,
+    ),
+    # http_transport=httpx.MockTransport(handler),  # deterministic offline seam
+)
+async with live_runner:
+    result = await live_runner.execute(request)
+```
+
+Here `request` is a public `HarnessExecutionRequest` whose compiled-harness and
+capability values agree with `live_runner.components`; the isolated package
+smoke in `scripts/installed_package_smoke.py` shows the complete request and a
+two-call fake OpenAI-compatible traversal. Consumer code does not import
+`millforge.model_backend`, `millforge._forge`, or checkout-only test helpers.
+
+The effective model-call timeout is the minimum of the request deadline, the
+resolved profile's `timeout_seconds`, and `local_total_seconds`; each HTTP phase
+is narrowed further by its named bound. The live runner owns and closes only the
+model client and HTTP client it creates. The secret resolver, clock,
+cancellation resolver, artifact-writer factory, and optional injected
+`AsyncHttpTransport` (including `httpx.MockTransport`) remain caller-owned.
+`aclose()` is idempotent,
+factory-owned resources close once, and execution after close raises
+`MillforgeBaseClosedError`.
+
+`HarnessExecutionRequest.stage` is provider-local: it identifies the compiled
+Millforge harness stage, not a caller workflow plane, node, route, dispatch
+identity, or authority. `MillforgeBaseRunner` admits exactly
+`StageIdentity(plane="execution", node_id="millforge-base",
+stage_kind_id="millforge_base")` and rejects every field mismatch before the
+private invocation executor, model, or tools are called. Caller-supplied
+`request_id` and `run_id` values are opaque correlation values; Millforge
+validates and echoes them unchanged but does not interpret them as routing,
+outcome, or terminal authority. An external adapter retains and applies any
+caller workflow identity and authority separately. Per-request
+`runner.invocation_evidence_for(request)` returns immutable, self-hashed
+invocation evidence that carries those same correlation values without adding
+workflow authority. Its request-local serialized schema is `1.2`; consumers
+must treat its digest as changed from the earlier composition-only evidence.
+
+Selected output is an opt-in, invocation-local request authority. The public
+`SelectedOutputRequirement` contract freezes one required/optional closed JSON
+schema and pins its canonical SHA-256 digest; `SelectedOutputAbsent` and
+`SelectedOutputPresent(value=None)` keep omission distinct from JSON `null`.
+Selected schemas and admitted values are bounded by named public ceilings and
+reject unsupported keywords/types, duplicate keys, non-finite numbers, invalid
+bounds, and oversized or excessively nested data. The selected schema digest
+and required/optional state appear in request-local invocation evidence only
+when authority is present; no-selection request serialization and behavior are
+preserved.
+
+For a custom subset, define an ordinary harness DSL graph with the desired
+Pi-compatible descriptor references and compile it through the normal
+Millforge compiler; `MillforgeBaseOptions` deliberately has no tool-selection
+setting. Millrace may select `millforge-base` as a compile-time default only
+when the pinned runner descriptor declares the current platform. On native
+Windows, default resolution must fail closed or select another explicitly
+configured supported runner; runtime fallback must never remap an already
+compiled Millforge binding.
+Millrace default selection, external workflow mapping, and live efficacy
+evaluation remain explicitly deferred to Millrace integration work.
+
+## Millforge 03A Closure Evidence
+
+Closure evidence for 03A was refreshed on `2026-06-14T09:11:34Z` for
+`task-03a-r2-04-closure-evidence-and-gates`.
+
+Contract coverage:
+
+- Source contract field table: `HarnessSource`, `StageScopeSource`,
+  `PromptSource`, `BudgetSource`, `ContextPolicySource`, `HarnessGraphSource`,
+  `HarnessNodeSource`, `PrerequisiteSource`, `ArgumentMatchSource`,
+  `ArtifactPolicySource`, and terminal artifact policies are implemented in
+  `src/millforge/compiler/source.py` with strict Pydantic v2 models,
+  `extra="forbid"`, frozen contracts, explicit defaults, identifier bounds,
+  collection bounds, tuple-backed snapshots, and mapping-to-record conversion.
+- Canonical YAML and equivalent JSON examples are covered by
+  `tests/compiler/test_parsing.py`; both front ends validate into the same
+  `HarnessSource` model.
+- Parser threat and limit matrix coverage includes duplicate keys, decoded key
+  equivalence, unsafe YAML aliases/anchors/merge keys/tags, non-string keys,
+  multiple documents, non-finite numbers, controls, invalid UTF-8, source size,
+  nesting depth, entry count, scalar size, numeric lexeme limits, JSON leading
+  whitespace, trailing JSON content, and top-level object requirements.
+- Diagnostic trigger evidence covers request, parse, schema, cross-field,
+  source-secret, ordering, truncation, and redaction cases in
+  `tests/compiler/test_diagnostics.py`, `tests/compiler/test_parsing.py`, and
+  `tests/compiler/test_requests.py`, including public unsupported-format parser
+  coverage for `MF-S005`, exact schema trigger coverage for `MF-S021`
+  unknown fields, `MF-S022` identifiers, `MF-S023` unversioned tool
+  references, `MF-S024` budgets, and `MF-S025` context policy values, plus
+  request-admission precedence for `MF-S018`.
+- Source-location examples cover parser and schema diagnostics with RFC 6901
+  field paths and one-based line/column locations.
+- Request and result serialized examples, result invariant matrix, raw request
+  admission examples, path-containment evidence, output-directory evidence,
+  source hash examples, replacement-race evidence, deep-snapshot proof, and
+  no-I/O/deferred-boundary proof are covered by `tests/compiler/test_requests.py`,
+  `tests/compiler/test_source.py`, and
+  `tests/compiler/test_frontend_boundaries.py`.
+- Schema-phase failure results preserve `source_document_sha256` and parsed
+  `harness_id` after a successful source parse, while request-phase and
+  parse-phase failures continue to omit parsed identity; `tests/compiler/test_requests.py`
+  covers the expected-harness mismatch and adjacent cross-field failure
+  boundaries.
+- Secret-helper evidence is covered without recording suspected source scalar
+  values; diagnostics and serialized outputs use redacted fields only.
+- Dependency and deferred-boundary audit evidence confirms compiler modules do
+  not import `_forge`, runtime execution, catalog resolution, HTTP/network,
+  subprocess, or model/tool invocation boundaries.
+
+Verification commands and results:
+
+```text
+python -m pytest
+732 passed, 1 skipped in 8.89s
+
+python -m ruff check .
+All checks passed!
+
+python -m ruff format --check .
+58 files already formatted
+
+python -m mypy .
+Success: no issues found in 35 source files
+
+python -m build
+Successfully built millforge-0.1.0.tar.gz and millforge-0.1.0-py3-none-any.whl
+```
+
+Source-control evidence:
+
+```text
+git diff --stat acd4491b905e635d6d3f9e9878206042a74692eb
+ README.md                                  |   90 ++
+ src/millforge/compiler/__init__.py         |  103 ++
+ src/millforge/compiler/diagnostics.py      |  400 ++++++++
+ src/millforge/compiler/parsing.py          | 1424 ++++++++++++++++++++++++++++
+ src/millforge/compiler/requests.py         | 1152 ++++++++++++++++++++++
+ src/millforge/compiler/source.py           |  375 ++++++++
+ src/millforge/compiler/validators.py       |  171 ++++
+ tests/compiler/test_diagnostics.py         |  159 ++++
+ tests/compiler/test_frontend_boundaries.py |   71 ++
+ tests/compiler/test_parsing.py             |  579 +++++++++++
+ tests/compiler/test_requests.py            |  955 +++++++++++++++++++
+ tests/compiler/test_source.py              |  203 ++++
+ 12 files changed, 5682 insertions(+)
+
+git status --short --branch
+## main...origin/main [ahead 1]
+```
+
+## Millforge 03B Semantic Compiler Boundary
+
+03B adds a private semantic compiler layer under `src/millforge/compiler/`.
+It consumes an accepted 03A `CompileInvocation` and `HarnessSource` plus one
+tool catalog snapshot and one model-profile snapshot. It resolves exact tool
+bindings and the compiled model profile, validates graph legality, top-level
+argument matches, required capability grants, and terminal-required artifacts,
+then produces a private immutable `ResolvedHarness` for later lowering.
+
+The resolved IR is not a public API and is not a compiled plan. 03B performs no
+source or output path I/O, source-file rereads, catalog refresh, plugin
+discovery, network calls, subprocess calls, runtime execution, output writes,
+compiled-plan hashing, or lowering. Those responsibilities are orchestrated by
+the 03C default compiler service in `src/millforge/compiler/service.py`, which
+delegates lowering to `src/millforge/compiler/lowering.py` and compiler output
+publication in `src/millforge/compiler/output.py`; runtime execution and
+registry/runtime work remain deferred.
+
+Remediated 03B closure evidence was refreshed on `2026-06-14T18:35:03Z` for
+`task-03b-r1-05-exact-closure-evidence-and-offline-gates`. The closure target is
+exact semantic parity with the canonical 03B root-source contract, not a new
+public compiled-plan or runtime result family. The evidence expects exact
+code-to-trigger coverage for catalog resolution, schema normalization, graph and
+argument validation, capability aggregation, artifact satisfiability, deferred
+scope, source-control state, and full offline gates.
+
+Representative 03B fixtures live under `tests/compiler/`:
+
+- `test_catalogs.py` covers catalog metadata capture, closed lookup outcomes,
+  `resolve_exact` protocol shape, immutable descriptor admission, model-profile
+  admission, lookup exception redaction, and reusable static snapshot fixtures.
+- `test_schema_validation.py` covers the compiler-owned JSON Schema subset,
+  scalar `const` replacement for `type`, `null` const values, declared enum
+  order, numeric scalar duplicate identity, deterministic normalization,
+  compatibility bytes, and checked-in golden parity vectors without importing
+  private Forge modules.
+- `test_graph.py`, `test_capabilities.py`, and
+  `test_artifact_validation.py` cover graph reachability and legality,
+  terminal-prerequisite separation from argument-match failures, exact
+  capability aggregation, artifact satisfiability, duplicate artifact IDs,
+  terminal-gated producer evidence, determinism, and no-cascade behavior.
+- `test_semantic.py` covers successful semantic compilation into the private
+  immutable IR, 03A failure pass-through without catalog access, catalog
+  resolution failures including `MF-R009` internal failures, duplicate bindings,
+  duplicate model tool names, capability and artifact failures, and
+  unresolved-node suppression.
+- `test_frontend_boundaries.py` audits compiler modules for deferred imports
+  and forbidden I/O/runtime invocation calls.
+
+## Millforge 03C Compiler Service, Lowering, and Output Boundary
+
+03C's default validated compiler service in `src/millforge/compiler/service.py`
+orchestrates admitted compile requests through semantic validation, lowering,
+compiled-hash verification, and atomic output publication. The service exposes
+the public typed `HarnessCompiler` boundary, reuses the parsed source carried
+by request admission, preserves front-end-before-catalog ordering, and returns
+immutable compile results with deterministic diagnostics.
+
+`tests/compiler/test_service.py` covers successful commits,
+front-end-before-catalog precedence, semantic failure normalization, and
+output-directory admission failure handling. `tests/compiler/test_lowering.py`
+covers accepted field shape, nested required fields, deterministic ordering,
+compiled-hash verification, and forbidden-data exclusion.
+`tests/compiler/test_output.py` covers request identity hashing, path
+confinement, admitted-directory revalidation, no-clobber reuse/conflict,
+durability failure handling, and diagnostics persistence.
+The compiler test area also includes checked-in YAML/JSON golden harness
+fixtures under `tests/compiler/fixtures/`, exact semantic and compiled-plan
+byte/hash assertions, output failure injection, and same-destination
+concurrent publication coverage. The representative golden fixtures cover
+three fixture pairs, including a rich case with two legal terminal results
+(`BLOCKED` and `BUILDER_COMPLETE`), a terminal-required artifact, all accepted
+budget fields, context phase thresholds, and multi-capability aggregation.
+Across all three cases, the representative fixture set pins exact diagnostics
+report shape and semantic-change hash movement without importing production
+Spec 07 preset ownership.
+Output diagnostics use the 03C root-source meanings: `MF-O001` for invalid
+output paths, `MF-O002` for diagnostics write failures, `MF-O003` for plan
+write failures, `MF-O004` for existing content-addressed output integrity
+failures, and `MF-O005` for temporary output cleanup failures.
+Lowering and internal diagnostics use the R2 root-source meanings:
+`MF-L001` for lowering invariant failures, `MF-L002` for accepted compiled-plan
+validation failures, `MF-L003` for source semantic hash failures, `MF-L004` for
+compiled hash verification failures, and `MF-I001` for bounded compiler
+internal errors.
+
+03C compiler output is the accepted `CompiledHarnessPlan` contract, not a
+compiler-specific plan shape. `source_document_sha256` remains compile-result
+evidence over the admitted normalized source document bytes, while
+`source_sha256` is stored in the emitted plan as the SHA-256 of the canonical
+validated semantic payload. The compiled hash is calculated by removing only
+the top-level `compiled_sha256` field from a complete JSON-mode plan payload,
+serializing with the shared canonical JSON encoder, hashing the UTF-8 bytes,
+reconstructing the final plan, and passing the shared
+`verify_compiled_plan_sha256()` verifier before output commit.
+The compiler service uses the shared
+`src/millforge/compiled_plan.py::calculate_compiled_plan_sha256()` helper for
+that pre-verifier check, preserving Arbiter criterion 7's single owned
+compiled-hash algorithm boundary.
+
+Emitted plan bytes are canonical compact UTF-8 JSON with one trailing newline
+and are published under the admitted output directory as relative
+`<url-escaped-harness-id>@<harness-version>.<compiled-sha256>.compiled.json`
+paths, for example
+`compiled/millforge.test.golden.compiler.v1@1.1d65583fe8bd8379d95f889fe0e889d9ee28ada85d912db9188191eb73bddc52.compiled.json`.
+Diagnostics remain request-addressed and use request-only,
+source-document-hash plus request-hash, or compiled-digest plus request-hash
+path forms such as
+`compiled/<harness-id>@<harness-version>.<compiled-sha256>.request-<request-identity-sha256>.diagnostics.json`.
+Diagnostics reports move from prepared to committed evidence only after plan
+publication is confirmed, and serialized diagnostics redact secret-looking
+messages and scalar fields before persistence. The
+`FileCompiledHarnessLoader` loads those emitted bytes through the same
+parse/hash/identity verifier used by runtime preflight. The focused
+compatibility test in `tests/compiler/test_service.py` removes the original
+harness source tree, loads only the emitted compiled bytes, and proves
+`DefaultHarnessRuntime` reaches the deterministic fake backend after preflight.
+
+Representative 03C coverage remains offline and deterministic. It covers the
+compiler-output boundary, hash stability, output-state guarantees, runtime
+loader/preflight compatibility, Forge adapter field compatibility, and package
+content inspection without live provider calls. The public offline Spec 07
+preset registry and readiness report now live in `millforge.eval_presets`,
+the public offline 08B eval-trial contract boundary, including
+caller-selected append-only campaign-store APIs, now lives in
+`millforge.eval_trials`, and the public offline 08C eval-reporting layer,
+including budget policy, live-admission diagnostics, metric aggregation, and
+deterministic JSON/Markdown report generation, now lives in
+`millforge.eval_reports`, while live Spec 07 execution and admission remain
+deferred to the owning workstream. The 08C `report.json`, `report.md`, and
+report-hash artifacts are deterministic offline evidence only: they document
+campaign contracts, budget/admission state, metrics, confounds, decision rules,
+and reproducibility hashes, and they explicitly do not support Pi-vs-Millforge
+model-performance conclusions from offline fake execution. The public offline
+`millforge.eval_suite` layer also offers `configure_offline_fake_eval_campaign()`
+for preflight and `run_offline_fake_eval_campaign()` for the full
+deterministic dry-campaign flow, which composes packaged fixtures, paired
+trial planning, offline fake execution, append-only campaign-store writes,
+resume indexing, and deterministic report generation under a caller-selected
+root. The same dry-campaign result now carries compact public closure evidence
+with deterministic hashes, counts, unresolved live dependencies, live-denial
+coverage references, Spec 07E treatment harness hash evidence, public hygiene
+flags, and an explicit offline-only claim boundary. No CLI is added for this
+slice: the public Python entry points keep the dry-run contract importable and
+testable while command UX, live runner orchestration, and operator-facing
+campaign controls remain deferred to the live-campaign workstream. Future live
+campaigns should reuse the same fixture-pack, trial-plan, append-only record,
+budget/admission, report, and closure-evidence contracts, replacing only the
+offline fake runner with admitted live Pi and Millforge runner execution.
+
+03C R2 closure evidence maps the latest Arbiter gaps to completed work:
+canonical lowering/internal diagnostic meanings, three representative YAML/JSON
+fixture pairs with exact semantic and compiled hashes plus diagnostics report
+shape assertions, and a complete deterministic failure-injection matrix across
+source semantic hashing, accepted-plan validation, compiled-hash verification,
+diagnostics persistence, plan output, publication, directory fsync, and
+temporary cleanup boundaries. The evidence continues to preserve the typed
+`HarnessCompiler` protocol, accepted `CompiledHarnessPlan` lowering, output
+addressing, same-plan concurrency, different-request diagnostics non-collision,
+and runtime compatibility through emitted compiled bytes loaded without the
+original source tree.
+
+## Millforge 03D Compiler Hardening and Spec 03 Closure
+
+03D closes the implemented Spec 03 compiler packet while preserving the
+accepted 03C baseline at commit
+`ebfa3ed205758780fef431674cf525e50f1559a5`. The final closure evidence is
+retained in the run-local conformance matrix and refreshed closure report for
+`task-03d-r4-03-closure-evidence-gate-refresh`, which preserved the exact
+offline gate set after the matrix parity pass and redacted the broad
+secret-pattern scan outputs.
+
+03D hardening adds or retains exact evidence for bounded parser adversarial
+coverage, source-contract property checks, graph oracle tests, catalog drift,
+descriptor-change hash behavior, capability/artifact validation, service
+failure precedence, deterministic compile variants, diagnostics sentinel
+redaction, filesystem/output failure injection, runtime loading from emitted
+compiled bytes, package/dependency boundaries, archive contents, Forge
+provenance, and unchanged `ref-forge/` state.
+
+Default verification remains offline and deterministic: the compiler suite,
+full pytest suite, Ruff lint, Ruff format check, MyPy, package build, wheel
+listing (`python -m zipfile -l dist/*.whl`), sdist listing
+(`tar -tzf dist/*.tar.gz`), baseline diff stat (`git diff --stat
+ebfa3ed205758780fef431674cf525e50f1559a5`), and source-control status
+(`git status --short --branch --untracked-files=all`) are the closure gates.
+The live OpenAI-compatible backend smoke remains opt-in and is not part of
+default closure.
+
+03D does not implement or claim Millrace runner binding, production built-in
+tool registry behavior, admitted connector compilation, small-model Millrace
+workflow behavior, production Spec 07 preset compilation, comparative
+evaluation workflow behavior, or live provider/model/tool execution. Those
+remain deferred to Spec 01, Spec 04, Spec 05, Spec 06, Spec 07, and Spec 08
+respectively.
+
+## Millforge 04A Tool Registry Core
+
+04A adds the public `millforge.tools` registry core. It provides immutable
+`ToolDescriptor`, `ToolTimeoutPolicy`, and `ToolOutputPolicy` contracts,
+registry-computed deterministic descriptor hashes, explicit in-process
+`ToolRegistry` registration, immutable exact-version
+`FrozenToolRegistrySnapshot` lookup, and projection into the existing compiler
+catalog and `ToolBindingRef` path.
+
+The package exposes registry constants, descriptor hash records, typed registry
+errors, and descriptor hash payload inspection helpers for deterministic
+evidence. Descriptor and snapshot hashing remains generic and registry-owned;
+04A does not ship production `builtin.*` descriptors, a default production
+registry, production presets, tool execution or dispatch, connector admission,
+live provider dependencies, or Millrace runner integration.
+
+## Millforge 04B Built-In Tool Descriptor Data
+
+04B adds the descriptor-only production `builtin.*` catalog data under
+`src/millforge/tools/`. It now spans 26 version-1 built-in descriptors for
+request inspection, workspace listing/reading/searching/writing/patching,
+named test execution, static checks, artifact read/write, terminal
+submit/reject/escalate actions, and the fixed artifact bridge readers and
+split verdict writers, all using the accepted 04A registry contracts.
+
+The built-in catalog stays import-safe and side-effect-free. It exposes the
+immutable descriptor set, deterministic registry construction helper, and
+frozen exact-version snapshot helper, but it still does not add tool execution,
+dispatch maps, connector admission, custom tools, production presets, queue
+policy, implementation registration objects, or Millrace runner integration.
+
+### Spec 07 Capability Projection Boundary
+
+Spec 07 compile cases validate concrete tool-level compiler/catalog grants,
+including `request.read`, `artifact.read`, `artifact.write`, `workspace.read`,
+`workspace.write`, `workspace.diff.read`, `process.test`,
+`process.static_check`, and `terminal.intent`. These grants are the catalog
+capability vocabulary used by built-in descriptors and semantic compilation.
+
+That vocabulary remains separate from the broader 06B eval-stage capability
+envelope concepts. 06B envelopes include `evidence.emit`, `runner.invoke`,
+`shell.run`, and broad workspace, package, network, git, and runtime-control
+envelopes. Spec 07 projects eval-stage needs into concrete compiler/catalog
+tool grants; it does not rename or replace the 06B capability names.
+
+The boundary is pinned by
+`tests/test_eval_presets.py::test_checker_compile_case_needs_tool_level_grants_not_only_06b_eval_envelope`
+and
+`tests/test_builtin_tool_catalog.py::test_builtin_descriptors_feed_capability_validation`.
+
+## Millforge 04C Tool Execution Boundary
+
+04C adds the compiled-plan-scoped runtime execution boundary under
+`src/millforge/tools/`. It exposes `create_builtin_tool_executor(...)` from
+`millforge.tools` and admits calls only through exact `ToolBindingRef`
+matches from the frozen compiled plan plus the accepted 04B built-in snapshot.
+
+Runtime implementations stay explicit and source-owned. Accepted built-in
+`implementation_id` values are registered to callables in source rather than
+descriptor import strings, dotted paths, plugin loading, connector lookup, or
+other dynamic dispatch.
+
+Binding denial is fail-closed and typed, with deterministic `not_found`,
+`conflict`, and `binding_mismatch` categories for uncompiled names, ambiguous
+model-visible names, runtime-implementation gaps, and projection mismatches.
+
+`DefaultHarnessRuntime` threads a runtime-owned `ToolExecutionContext` through
+the guarded session and into the tool-executor bridge, so tool dispatch uses
+trusted request, stage, run, workspace, artifact, capability, deadline, and
+cancellation data supplied by the runtime rather than model-authored
+substitutes.
+
+### Execution Validation, Results, And Traces
+
+Model tool calls are converted into closed `ValidatedToolCall` objects before
+implementation entry, so extra fields are rejected by schema rather than
+flowing into the runtime.
+
+The runtime rechecks prerequisites, required capabilities, deadlines, and
+cancellation before dispatch. Built-in calls also pass through an
+executor-owned, non-effectful pre-entry policy gate before implementation
+entry, covering workspace logical-path containment, artifact declarations and
+availability, shell profile/selector/timeout admission, and terminal artifact
+requirements. The runtime validates implementation output against descriptor
+output schemas after completion and fails closed on invalid output before
+model-visible return, then redacts and bounds accepted results before return.
+
+Every attempted or denied call emits a `ToolTraceRecord`. Pre-entry denials
+persist `side_effect_certainty=not_attempted`, and resolved, ambiguous, and
+uncompiled binding states are preserved through `binding_resolution_status`.
+Connector traces also carry structured approval, drift, request/response,
+retry, and redacted-evidence fields so failures stay auditable without prose
+summaries.
+
+## Millforge 04D Tool Registry Closure Evidence
+
+04D closes the accepted Spec 04 tool-registry packet with retained offline
+evidence rather than new production authority. The closure surface is the
+machine-checkable conformance matrix at
+`tests/fixtures/spec04_conformance_matrix.json`, validated by
+`tests/test_tool_registry_closure.py`, plus focused readiness tests for the
+04A registry contracts, 04B built-in descriptor catalog, and 04C built-in
+execution boundary.
+
+The package and documentation audits keep the public claim narrow:
+implemented Spec 04 behavior covers registry descriptors, built-in catalog
+data, exact compiled-plan tool binding, built-in execution policy gates,
+trace/result evidence. Offline 05A through 05D closure work adds connector
+admission, runtime-boundary admission snapshots, compile-only custom-tool
+descriptors, and mixed registry/catalog/compiler evidence through the generic
+tool path. Deferred live connector transport, marketplace installation,
+production stage presets, Millrace runner integration, eval-suite execution,
+live connector execution, and live provider/model/tool execution remain
+deferred.
+
+Default Spec 04 closure verification is offline and deterministic. The retained
+gate set includes the focused registry closure suite, the full pytest suite,
+Ruff lint and format checks, MyPy, `pip check`, package build, wheel and sdist
+archive listings, the accepted 04C baseline diff, source-control status, and
+private-state checks for `millrace-agents/`, `ideas/`, and `ref-forge/`.
+
+## Millforge 05A Connector Descriptor Admission
+
+05A adds the public `millforge.connectors` package for deterministic offline
+connector descriptor admission. It exposes frozen connector identity, discovery
+snapshot, admission manifest, admission policy, admission result, admission
+record, and diagnostic contracts, plus `admit_connector_tools(...)` for
+lowering explicitly admitted discovered tools into existing immutable
+`ToolDescriptor` objects.
+
+Discovery snapshots are evidence only: they are not tool catalogs, do not
+implement `ToolCatalogSnapshot`, and are rejected before semantic compilation
+can resolve model-visible tools. Admitted connector descriptors continue through
+the generic `ToolRegistry`, `FrozenToolRegistrySnapshot`, and compiler catalog
+path rather than a connector-specific runtime catalog.
+
+Connector input and output schemas are normalized through the accepted
+compiler-owned JSON Schema subset. Unsupported bound keywords such as
+`maxLength`, `maxItems`, `minimum`, and `maximum` are rejected at admission
+with explicit schema-error diagnostics because runtime does not enforce those
+bounds.
+
+05A remains offline and descriptor-only. It does not implement real MCP stdio
+or HTTP transport, connector process launching, sockets, live connector
+discovery, live connector invocation, credential use, a runtime connector
+broker, production connector presets, Millrace runner integration, or
+Millrace approval token handling.
+
+## Millforge 05B Connector Runtime Admission Snapshot
+
+05B adds the runtime-owned `ConnectorAdmissionSnapshot` and
+`ConnectorAdmissionBinding` contracts, plus the connector-scoped
+`ConnectorBroker`, `ConnectorInvocationRequest`, and `ConnectorBrokerOutcome`
+runtime boundary. The snapshot deep-freezes accepted 05A
+`ConnectorAdmissionRecord` evidence into exact bindings keyed by `tool_id`,
+`tool_version`, and `descriptor_sha256`, exposes a deterministic
+`snapshot_sha256`, and preserves `connector_id`, `provider_tool_name`,
+`connector_identity_sha256`, `discovery_snapshot_sha256`, `raw_tool_sha256`,
+`input_schema_sha256`, `output_schema_sha256`, `provider_description_sha256`,
+`required_capabilities`, `side_effect_class`, `idempotency`,
+`timeout_policy`, `output_policy`, optional `idempotency_key_policy`,
+`approval_policy`, and `admission_record_sha256`. `CompiledToolBindingExecutor`
+and `create_tool_executor(...)` require that the snapshot and broker be
+provided for compiled connector descriptors while built-in-only plans continue
+to construct and execute unchanged.
+
+Before broker entry, the executor revalidates broker-exposed provider evidence
+against the admitted connector identity, discovery snapshot, raw tool, and
+schema or description hashes when those fields are available. It also
+compares preserved admission `required_capabilities` against the compiled
+connector descriptor before broker entry; capability drift fails closed with a
+`binding_mismatch` denial that stays distinct from ordinary runtime
+capability-grant failures.
+
+Broker requests are keyed by `connector_id` and `provider_tool_name`, carry
+validated JSON object arguments plus `tool_id`, `tool_version`,
+`descriptor_sha256`, and runtime provenance, and stay narrow enough for the
+offline `DeterministicFakeConnectorBroker` to keep connector boundary tests
+deterministic.
+
+Snapshot construction fails closed for missing, duplicate, stale,
+descriptor-inconsistent, or non-connector admission records, and later source
+mutation cannot change the frozen runtime bindings.
+
+## Millforge 05C Custom-Tool Mini-Compiler
+
+05C adds the public `millforge.custom_tools` package for deterministic offline
+custom-tool contracts and diagnostics. It exposes frozen source manifest,
+declaration, compiler policy, compilation record, compilation result, and
+diagnostic contracts, plus `compile_custom_tools(...)`, deterministic hash
+helpers, and validation helpers for raw contract inputs.
+
+Accepted `runtime_kind=contract_only` declarations lower into immutable hashed
+`ToolDescriptor` data and one immutable `CustomToolCompilationRecord` per
+descriptor while remaining compatible with the existing `ToolRegistry`,
+`FrozenToolRegistrySnapshot`, and compiler catalog path. Accepted results
+normalize descriptor and record ordering by package, tool, version,
+model-facing identity, implementation, descriptor hash, and record hash, while
+rejected diagnostics are sorted canonically with evidence-aware tie-breakers.
+The contracts keep explicit UTC provenance, closed approval/runtime enums, and
+redacted bounded diagnostics for malformed source.
+
+05C stays compile-only. It does not register executable custom-tool runtime
+implementations, expose a custom tool registry or catalog, launch tools, broker
+connectors, run sandboxed code, integrate with a runner, or claim executable
+runtime support.
+
+## Millforge 05D Mixed Connector And Custom-Tool Closure
+
+05D adds deterministic offline closure evidence that combines built-in,
+admitted connector, and compiled contract-only custom-tool descriptors through
+the existing `ToolRegistry`, `FrozenToolRegistrySnapshot`, compiler catalog,
+semantic validation, lowering, and compiler service path. The machine-readable
+conformance matrix at `tests/fixtures/spec05_conformance_matrix.json` and the
+focused smoke in `tests/test_connector_custom_tool_closure.py` back the mixed
+registry, mixed catalog, harness selection, and illegal tool-denial rows.
+
+The closure fixtures cover connector discovery, admission manifest, admission
+policy, custom-tool source manifest, expected hashes, and a mixed harness
+fixture under `tests/fixtures/spec05_mixed_harness/`. 05D remains offline and
+does not add live connector transport, marketplace installation, automatic
+discovery or admission, custom runtime execution, runner integration, eval
+workflows, or live model/backend validation.
+
+### Opt-In Live Model Backend Smoke
+
+Normal test runs are offline, deterministic, and do not require provider
+credentials. The live OpenAI-compatible backend smoke is marked
+`live_model_backend` and is skipped unless explicitly enabled:
+
+```bash
+MILLFORGE_LIVE_MODEL_BACKEND_SMOKE=1 \
+MILLFORGE_LIVE_MODEL_PROFILE_ID=<profile-id> \
+MILLFORGE_LIVE_MODEL_PROVIDER_ID=<provider-id> \
+MILLFORGE_LIVE_MODEL_ID=<model-id> \
+MILLFORGE_LIVE_MODEL_BASE_URL=<openai-compatible-base-url> \
+MILLFORGE_LIVE_MODEL_SECRET_ID=<secret-ref-id> \
+MILLFORGE_LIVE_MODEL_SECRET_ENV_VAR=<credential-env-var-name> \
+<credential-env-var-name>=<credential> \
+python -m pytest -m live_model_backend tests/test_model_backend.py
+```
+
+Optional variables: `MILLFORGE_LIVE_MODEL_AUTH_SCHEME` (`bearer` or `header`),
+`MILLFORGE_LIVE_MODEL_AUTH_HEADER` for custom header authentication,
+`MILLFORGE_LIVE_MODEL_TIMEOUT_SECONDS`, and
+`MILLFORGE_LIVE_MODEL_MAX_OUTPUT_TOKENS`. The smoke records only sanitized
+provider, model, latency, finish reason, and usage metadata.