murmur-artifact 0.8.0

The shared artifact model for Murmur capsules: manifest schema, .mur.zip packing and unpacking, the registry trait, refs, lockfile, and inference config.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Registry of `W-RUN-*` codes for non-fatal warnings a session raises while it is running.
//!
//! Mirrors [`crate::security_warnings`], [`crate::registry_warnings`] and
//! [`crate::build_lints`]: the session still produces a result and still ends `ok`, so the code
//! is printed rather than raised. Each code has a matching `#w-run-nnn` anchor on the
//! diagnostics reference page, so callers append [`runtime_warning_link`] instead of
//! re-explaining the issue inline.
//!
//! These fire mid-session, after the loop has been running, so they go to stderr alone. The
//! staging-time `W-SEC-*` warnings also land in `logs/bootstrap.log`, which is closed to writes
//! by the time a turn happens.
//!
//! Numbers 005 and 006 are retired and never reused.

/// A turn the provider cut off at the `inference.max_tokens` output cap.
///
/// The reply in `out/result.txt` is a fragment of what the model was writing, not the answer it
/// meant to give. Nothing failed — the provider honoured the cap the capsule asked for — so the
/// session ends `ok` and the truncation is named instead.
pub const W_RUN_001: &str = "W-RUN-001";

/// The harness a `transport: process` capsule runs was not one its process driver was tested
/// against, or its version could not be read at all.
///
/// The driver translates for a harness whose flags and output format move between releases, so an
/// untested version may be driven wrongly in ways that only show up mid-run. Nothing is refused:
/// the run proceeds on the driver as written, and the version gap is named instead.
pub const W_RUN_002: &str = "W-RUN-002";

/// An `inference.alternates` driver choice whose credential could not be resolved at launch.
///
/// The primary is what the launch needs, and an alternate is an option, so nothing is refused:
/// the choice is staged unavailable, and a switch to it is refused when it is asked for.
pub const W_RUN_003: &str = "W-RUN-003";

/// A tool's `input_schema` is malformed where the required-field check reads it: the root is not
/// a JSON object, or its `required` is not an array of strings.
///
/// A malformed schema is a bad tool rather than a bad call, so nothing is refused: the check is
/// skipped for that tool, its calls are dispatched unchecked, the session continues, and the
/// malformation is named once per tool per session.
pub const W_RUN_004: &str = "W-RUN-004";

/// A `mur run` that carries a formation id but was handed no lifeline, and is no delegated child.
///
/// Such a session is a formation member someone started by hand, usually to debug it. It runs as
/// any other `mur run` does, but nothing will wind it down when its formation ends; the warning
/// names the formation and `mur stop` as the way to end it. Printed once, at launch.
pub const W_RUN_007: &str = "W-RUN-007";

/// A formation member the roster lets call another whose `capabilities.network.allow` reaches no
/// loopback `http` door at an unpinned port.
///
/// A roster edge grants a name and a credential, never egress, and a callee's door is served at a
/// port chosen at launch, so every `call-member` call from such a member is refused. Nothing is
/// refused at launch: the member may still be called. Printed once, at staging.
pub const W_RUN_008: &str = "W-RUN-008";

/// A driver choice whose driver's `models:` table lists no limits for its model, in a capsule
/// that sets `inference.max_tokens` but not `context.max_tokens`.
///
/// The output cap is the operator's own, so nothing is refused; with no context window known,
/// compaction does not run and no seed budget applies for that choice. Printed once per choice, at
/// staging, and by `mur doctor` with the same text.
pub const W_RUN_009: &str = "W-RUN-009";

/// Builds the doc link for a `W-RUN-*` code, e.g. `.../diagnostics/#w-run-001`.
pub fn runtime_warning_link(code: &str) -> String {
    crate::diagnostic_link(code)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every code is distinct and spelled in the `W-RUN-NNN` shape the diagnostics page anchors
    /// on. A duplicated or misspelled constant would silently point two warnings at one anchor.
    #[test]
    fn every_code_is_unique_and_well_formed() {
        let codes = [
            W_RUN_001, W_RUN_002, W_RUN_003, W_RUN_004, W_RUN_007, W_RUN_008, W_RUN_009,
        ];
        for code in codes {
            assert!(code.starts_with("W-RUN-"), "malformed code: {code}");
            assert_eq!(code.len(), 9, "malformed code: {code}");
        }
        let mut unique = codes.to_vec();
        unique.sort_unstable();
        unique.dedup();
        assert_eq!(unique.len(), codes.len(), "two W-RUN codes are equal");
    }

    #[test]
    fn link_lowercases_the_code_into_the_anchor() {
        assert_eq!(
            runtime_warning_link(W_RUN_001),
            "https://docs.murmur.nexus/reference/diagnostics/#w-run-001"
        );
    }
}