Table of Contents

Binary rule packs

A binary rule pack (.bcal) is the compiled form of a notable-date document: a compact, integrity-checked, sealed encoding of a validated NotableDateResource. Packs are written at build/authoring time, where the writer runs the loader's checks, and loaded at run time without parsing or semantic validation - the trim- and AOT-friendly load path for calendar data.

When to use a pack

  • Trimmed / native-AOT deployments. Loading a pack touches no XML/JSON machinery and no reflection; every strategy is reconstructed through a closed table of one-byte discriminators. This is the data-driven alternative the plugin loader's [RequiresUnreferencedCode] annotations point at.
  • Startup cost. A pack skips the parse → import-resolution → validation pipeline entirely; only bounds checks and an integrity digest run at load.
  • Sealed deployment artifacts. A pack cannot carry anything the shipped engine does not already implement, and corruption or truncation fails the payload digest. The digest is an unkeyed SHA-256 kept in the pack's own header, not a signature: someone who edits a pack can recompute it, and a pack is not revalidated as a document is when it loads. Load packs only from your own build or deployment, as the untrusted input topic explains.

Producing and loading packs

// Compile: author (or load) a document, then save it as a pack. Build() runs first,
// so only content that passed the canonical loader's validation is ever encoded.
NotableDateDocumentBuilder builder = NotableDateDocumentBuilder.Create("corp.holidays")
    .AddNotableDate("company-day", "Company Day", NotableDateCategory.Observance, d => d
        .AddRule("default", r => r.Fixed(3, 14)));

builder.Save("corp-holidays.bcal");             // extension selects the binary format
builder.SaveBinary("corp-holidays.bcal");       // or explicitly

// Load: the runtime-side entry point skips parsing and validation.
using FileStream stream = File.OpenRead("corp-holidays.bcal");
NotableDateResource resource = NotableDateResourceLoader.LoadBinary(stream);
INotableDateService service = new NotableDateService(resource);

The symmetric low-level surface is NotableDateBinaryResource - Write(resource, stream) / Read(stream) - usable with any already-built resource, including the bundled catalogues. Write runs the loader's identifier, range, enumeration, duplicate and cross-reference checks on the resource before it encodes anything, and refuses one the loader would reject with NotableDateValidationException, carrying the diagnostics the loader reports (such as BODU-CAL-SCHEMA for a concept id of New-Year, or BODU-CAL-DUP-ND for two concepts sharing an id), so a resource assembled in code is held to the rules a document is. A resource whose algorithm strategies name keys from a custom registry is written with Write(resource, stream, algorithms), as it was loaded with that registry.

A pack is compiled output, not an authoring source: NotableDateDocumentBuilder.Load rejects .bcal paths with NotSupportedException. Keep the XML/JSON document as the editable source of truth and recompile.

Guarantees

Guarantee Meaning
Pre-validated content Write runs the loader's identifier, range, enumeration, duplicate and cross-reference checks on the resource before encoding anything, and SaveBinary runs Build() (the canonical loader) first, so neither an invalid document nor a resource the loader would reject can reach a pack. Reading does not revalidate: a pack not produced by Write, such as one edited by hand and given a matching digest, is checked only as the Sealed row describes.
Byte stability The same resource always encodes to the same bytes - dictionary content is key-sorted and string interning follows deterministic traversal - so build systems can rely on pack outputs for up-to-date checks.
Integrity The header carries a SHA-256 digest of the payload; any corruption or modification fails the load before content is interpreted.
Sealed The reader rejects unknown format versions, unknown discriminators, undefined enum values, out-of-range string references, truncation at any byte, trailing bytes, and values outside a model constructor's domain - always as NotableDateBinaryFormatException (a FormatException), never as an unrelated failure.
Behavioural fidelity A round-tripped resource resolves identically to the original; the test suite pins resolved-occurrence parity for every bundled catalogue and a synthetic document covering every strategy, recurrence, and duration type.

Format layout (versions 1, 2 and 3)

Versions 1, 2 and 3 share one layout, and a pack is written at the lowest version whose meaning it needs. A pack is written at version 1 unless an adjustment scope names a concept's rule (<Rule notableDateRef="…" ruleRef="…" />): such a scope stores the reference as notableDateRef/ruleRef, and the pack is written at version 2 so that a reader from before qualified references rejects it instead of matching the reference against rule identifiers alone. A pack whose spanCollisionPolicy is not KeepAll, or whose observedDateRangePolicy is not ObservedOccurrenceControlsInclusion, is written at version 3, whatever its scopes hold, so that a reader from before those policies were applied rejects it instead of resolving it as though they were their defaults. The duplicatePolicy needs no version of its own: a pack is written from a loaded resource, whose duplicates the policy has already settled. Version 1 packs scope by rule identifier alone, which matches that rule in every concept; the reader accepts all three versions and keeps that meaning for a version 1 pack.

Multi-byte integers are little-endian. varuint is the 7-bit variable-length encoding; signed values use ZigZag over varuint. Strings are referenced by 1-based index into a deduplicating table (index 0 = null); dates are day numbers.

header   := "BCAL" version:u16 flags:u16 payload-sha256:32B
payload  := string-table body
string-table := count:varuint { length:varuint utf8-bytes }*
body     := resourceId schemaVersion resolution-policy
            adjustment-policies:count-prefixed
            notable-dates:count-prefixed

Rules encode nullable fields as presence bytes and their occurrence source as a marker byte (1 = calculation strategy, 2 = recurrence) followed by a discriminator byte and that type's fields. The discriminator tables enumerate the engine's 13 calculation strategies, 4 recurrence strategies, and 2 duration definitions exhaustively; additions require a new format version, which this reader rejects.

Compiling packs from the command line

The bodu-calendar dotnet tool wraps the same compile pipeline for scripts and CI - it validates a notable-date document with the stable BODU-CAL-* diagnostics and compiles it to a sealed pack without writing any C#:

# Not on nuget.org: pack the tool from a clone and install it from that local feed.
dotnet pack Bodu.Globalization.Calendar.Tool/src -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts Bodu.Globalization.Calendar.Tool

bodu-calendar lint holidays.xml
bodu-calendar compile holidays.xml -o holidays.bcal
bodu-calendar info holidays.bcal

lint reports every diagnostic in collect mode, compile refuses to write a pack from a document that fails validation, and info prints a compiled pack's header, counts, and integrity digest.

Compiling packs during build

The Bodu.Globalization.Calendar.Build package adds MSBuild integration - a development dependency that compiles NotableDatePack items to .bcal incrementally on every build via the bundled bodu-calendar tool, with no runtime reference added to the consuming project.

It is not published to nuget.org, so pack it from a clone into a local feed and reference the package, or import its .targets from the clone; Compiling packs in MSBuild shows both. A ProjectReference to the Build project alone compiles nothing, because it does not import the .targets. Either way, the project declares its documents as NotableDatePack items:

<ItemGroup>
  <NotableDatePack Include="rules\holidays.xml" />
  <NotableDatePack Include="rules\corporate.json" ResolverDir="rules\shared" />
</ItemGroup>

Each item compiles to $(NotableDatePackOutputPath)<Filename>.bcal (defaulting under the intermediate output path) and is copied to the project output directory; set NotableDatePackCopyToOutput to false to keep packs out of the output folder.

Where to go next