Malib 0.1.0-preview.14

Malib .NET Binding

Malib is an embeddable text analysis and transformation engine inspired by Matla. This package exposes a .NET API over the native Malib runtime.

Install

dotnet add package Malib

The NuGet package bundles the native matlalib_ffi and compatible FastParse runtimes under runtimes/*/native for supported platforms. Grammar-aware when ast rules work without installing a second package. During local development without packed native assets, set:

export MALIB_NATIVE_LIBRARY_PATH=/path/to/libmatlalib_ffi.dylib

You can also call MalibNative.ConfigureLibraryPath(...) before the first Malib call.

Malib Language Documentation

The package includes the version-matched Malib language documentation under:

docs/malib/

AI agents should open docs/malib/package-bootstrap.json first when working from an installed package. It uses schema malib.package.bootstrap.v1 and points to the shortest path through docs/malib/AI-AGENT-GUIDE.md, docs/malib/language-metadata.json, workflow guides, schema contracts, agent evals, and release verification commands.

.NET hosts can locate that file with:

var bootstrapPath = MalibDocumentation.GetRequiredPackageBootstrapPath();
var bootstrapJson = MalibDocumentation.ReadRequiredPackageBootstrapJson();
var evalManifest = MalibDocumentation.ReadRequiredDocsText("agent-evals/manifest.json");
var contractEvidence = MalibDocumentation.ReadRequiredContractEvidenceSummary();
Console.WriteLine(contractEvidence.Summary.DocumentedOnly);
Console.WriteLine(contractEvidence.Gaps.GoldenWithoutFixture.Count);

The package root also includes CHANGELOG.md with the version-by-version release history. Malib release and smoke workflows verify this documentation bundle against docs/malib/language-metadata.json, including package bootstrap, schemas, fixtures, and agent evals, before publishing. The NuGet smoke programs also validate packaged trace, coverage, and final run report APIs against malib.trace.event.v1, malib.coverage.v2, and malib.run.report.v1 evidence.

Minimal Example

using Malib;

using var program = MalibProgram.Compile("""
debug on all
coverage on
let found = 0
when ("IF") {
  found = 1
}
export { found: found }
""");

var result = program.RunText(
    "IF A\n",
    new MalibRunOptions
    {
        SourceName = "memory.cbl",
        Profile = true,
        Trace = true,
        Coverage = true,
        Report = true
    });

Console.WriteLine(result.Variables["found"].AsString());
Console.WriteLine(result.Profile?.RuleMatches);
Console.WriteLine(result.Trace.Count);
Console.WriteLine(result.Coverage?.Totals?.Matched);
Console.WriteLine(result.Coverage?.Rules[0].Rule);
Console.WriteLine(result.Coverage?.TokenStates[0].CausedBy[0].Action);
Console.WriteLine(result.Report?.Schema);
Console.WriteLine(result.Report?.RuntimeEffects.GetRawText());

Contract

• MalibProgram owns a native compiled program handle and must be disposed.
• MalibProgram.Compile(string) compiles Malib source from memory.
• MalibProgram.CompileFile(path) compiles a .malib file and resolves relative import ruleset, import analyzer, and import fun modules from that file's directory.
• MalibProgram.CompileProject(path) compiles a project directory by resolving src/main.malib first, then main.malib. Use this for modern modular Malib projects with src/rulesets, src/analyzers, and src/fun modules.
• RunText and RunBytes run source content from memory; the parent application owns source, stream, and general application IO.
• Physical SQLite and SQLite RAM functions inside Malib programs are enabled by the bundled native runtime: sqlite_query, sqlite_execute, sqlite_insert_many, sqlite_ram_query, sqlite_ram_execute, sqlite_ram_insert_many, and the RAM-backed table_* helpers. Physical functions operate on database file paths visible to the native process.
• grammar "java" and when ast use the bundled FastParse provider lazily. Grammar declarations have zero AST parse cost until a structural rule runs. Optional language extensions are discovered by canonical grammar name from the packaged native directory or FASTPARSE_GRAMMAR_PATH.
• MalibResult exposes prints, flags, variables, export data, token count, optional profile metrics, optional structured trace events, optional coverage audit data, and optional malib.run.report.v1 final run reports.
• Trace = true returns debug events enabled by Malib source such as debug on all; it does not enable debug by itself. when_match and when_no_match trace events expose MalibTraceEvent.Group and MalibTraceEvent.Rule; all trace events include common JSON fields such as effect_type, subject, rule_attributed, and attribution for agent-friendly triage.
• Coverage = true returns coverage on token audit data with schema malib.coverage.v2, totals, per-rule aggregates, per-token states, and per-token CausedBy evidence; it does not enable coverage by itself.
• Report = true returns a compact AI-friendly final run report with malib.runtime.effects.v1 logical effect summaries, including per-rule by_rule, by_variable, by_flag, and by_source_operation attribution, and enables profile collection for that run.
• MalibValue wraps structured Malib values as JSON-backed text, list, and object accessors.
• Native pointers are not exposed through the public .NET API.
• MalibDocumentation.ReadRequiredContractEvidenceSummary() reads the package-versioned malib.contract.evidence.v1 snapshot as a typed object for Matla/Malib compatibility evidence. Use FindEntry("MCM-0160") to inspect a specific mapping. Use Gaps.DocumentedOnly, Gaps.GoldenWithoutFixture, and Gaps.FixtureWithoutGolden to prioritize new fixtures and golden runs.

Threading

A compiled MalibProgram is intended to be reusable across executions. Do not dispose a program while another thread is running it. Until dedicated concurrent binding tests are added, prefer one MalibProgram per worker for production parallelism.

Errors

Native compile and runtime failures are surfaced as MalibException. Inspect MalibException.StructuredDiagnostic first: parser/compiler failures use malib.language.diagnostic.v1 with stable M#### code, category, optional source span, help text, and docs anchor. Runtime failures may also include the compatibility accessor MalibException.Diagnostic, a JSON-backed malib.runtime.diagnostic.v1 object with stable MR#### code, category, message, suggestion, and docs anchor.

try
{
    program.RunText("IF A\n");
}
catch (MalibException ex) when (ex.Diagnostic is not null)
{
    Console.WriteLine($"{ex.Diagnostic.Code}: {ex.Diagnostic.Suggestion}");
}

try
{
    MalibProgram.Compile("when (\"IF\") {\n  nope\n}\n");
}
catch (MalibException ex) when (ex.StructuredDiagnostic is not null)
{
    Console.WriteLine($"{ex.StructuredDiagnostic.Code}: {ex.StructuredDiagnostic.Help}");
}