Skip to content

About

Reusable packaged libraries aligned to the Frontier Architecture

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Frontier Platform

Reusable platform libraries for the Frontier workflow orchestration platform, published as NuGet packages to GitHub Packages.

These thirteen libraries are a severable sub-graph: no platform assembly references any Frontier.Reason.* assembly, at either the assembly-reference or the type-dependency level. That guarantee is what allowed them to be extracted from the frontier-workflow repository into this one, and it is enforced here by architecture tests rather than left to convention (see docs/DECISIONS.md, ADR-PA2).

Two tiers, and the dependency runs one way

  • Governance tier — Abstractions, Serialization, Audit, ContextAssembly, Contracts, Guardrails, Hitl, ModelRoleConfig, Observability, Resilience. Flat: each references only Abstractions and Serialization among platform libraries, so each stays independently consumable and taking one never drags in a sibling.
  • Engine tier — Workflow.Model, Workflow.Orchestration, Workflow.Compiler. May depend on governance, because walking a DAG is calling an approval store, assembling context and resolving a model.

The half that carries the weight is the direction. GovernanceLibrary_DoesNotDependOnTheEngine asserts that no governance library references an engine assembly — a solution that wants audit or approvals and no interpreter at all must still be able to take them. A single reference the wrong way would collapse the tiers back into one graph, and it would compile perfectly, which is why it is a test rather than a convention (ADR-PA5).

Packages

Governance tier

Package Owns
Frontier.Platform.Abstractions The platform contract kernel: SmartEnum<T>, IVersionedContract, ContractMigrator, the permanent-failure exceptions, and the shared kernel contracts. Zero dependencies (ADR-PA1).
Frontier.Platform.Serialization The canonical JSON profile. Byte-stable output — definition hashing, cache hits and audit signing all depend on it.
Frontier.Platform.ContextAssembly Tiered context assembly (baseline → dynamic → real-time) with provider cache breakpoints at tier boundaries.
Frontier.Platform.Contracts Contracts as data (ADR-PA38): the registration check for a registry contract (2020-12 meta-schema, local references only, legibility lint, compatibility within a major) and the one validator the engine runs at node boundaries. JSON Schema through Corvus.Text.Json.Validator and CEL rules through Celly, each behind an internal port.
Frontier.Platform.Audit Audit record contracts, hash chaining and verification, Cosmos-backed stores, and change-feed archival export.
Frontier.Platform.Hitl Human-in-the-loop approval store, queries and rollback. Solution-agnostic: callers drive it from their own orchestration activity shells.
Frontier.Platform.ModelRoleConfig Model role registry and resolution: capability requirements, fleet/canary mappings, mapping governance.
Frontier.Platform.Resilience Retry, circuit-breaker and bulkhead policy specifications with failure classification, translated to named Polly v8 profiles.
Frontier.Platform.Observability Telemetry contracts and metric catalogue.
Frontier.Platform.Guardrails Admission control and budget enforcement over a Cosmos-backed ledger.

Engine tier

Package Owns
Frontier.Platform.Workflow.Model The definition and execution model: the typed DAG a workflow compiles to, and the vocabulary its execution is recorded in. Inert — it declares shape and executes nothing.
Frontier.Platform.Workflow.Compiler Structural validation, the design-language schema, the publish lifecycle (draft → validate → propose → approve → publish), and the design agent.
Frontier.Platform.Workflow.Orchestration The interpreter: the durable orchestrator that walks a compiled DAG, its activity shells, the agent and tool invocation pipelines, and audit consolidation. Vendor-neutral — model providers and tool transports arrive through consumer-owned ports.

Each package has its own README with its DI entry point, the ports its consumer must supply, and the invariants it enforces.

Consuming the packages

GitHub Packages requires authentication even for public packages, so a personal access token with the read:packages scope is needed regardless of repository visibility.

Add a nuget.config beside your solution:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="frontier" value="https://nuget.pkg.github.com/markchivs73/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <frontier>
      <add key="Username" value="%GITHUB_USERNAME%" />
      <add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
    </frontier>
  </packageSourceCredentials>
</configuration>

Then set GITHUB_USERNAME and GITHUB_TOKEN in your environment and reference the packages normally. Do not commit the token.

Versioning

Versions are derived from git tags by MinVer: tagging v1.2.3 on main publishes 1.2.3. Untagged builds get a height-suffixed prerelease off the last tag.

All thirteen packages version in lockstep from a single tag — a change to one library republishes all thirteen at the new version. That is a deliberate trade: one tag and one set of release notes instead of twelve of each. See docs/DECISIONS.md.

A release is a release: Ship vX.Y.Z pull request that moves every package's PublicAPI.Unshipped.txt entries into PublicAPI.Shipped.txt (python3 tools/ship-public-api.py), then a tag on its merge commit. The publish workflow refuses any other tag, and once the packages are pushed it creates the GitHub Release with notes generated from the pull-request titles since the previous tag. The git-workflow skill has the steps.

While the major version is 0, breaking changes may appear in a minor release.

Build and test

dotnet build FrontierPlatform.slnx -c Release   # warnings are errors
./tools/run-unit-tests.sh                       # unit + architecture tests, coverage gate

run-unit-tests.sh mirrors the CI test job exactly, including the ≥95% per-assembly line-and-branch coverage gate. Run it before pushing.

The integration tests need a Cosmos emulator. They provision and tear down their own databases, so no setup script is required:

docker run -d --name cosmos-emulator -p 8081:8081 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http

dotnet test FrontierPlatform.slnx -c Release --filter "Category=Integration"

Set COSMOS_EMULATOR_ENDPOINT if the emulator is not on http://localhost:8081.

That solution-wide run is fine without coverage. The CI integration job runs each test project in turn with --collect:"XPlat Code Coverage" --settings coverlet.runsettings, and puts a per-assembly table beside the unit gate's in the job summary. That table is a report, not a gate.

The orchestration replay suite (GraphOrchestratorReplayTests) also needs the Durable Task Scheduler emulator, at the digest CI pins:

docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 \
  -e Database__TaskHubNames__0=frontier-platform-replay \
  mcr.microsoft.com/dts/dts-emulator@sha256:361323065a608d605f9d3ae56b854eb11f1c47fcc16845a37f948f03ca9c5fac

DTS_EMULATOR_ENDPOINT (default http://localhost:8080) and DTS_EMULATOR_TASKHUB (default frontier-platform-replay) override. The frontier-workflow dev stack's emulator also listens on 8080 but serves the frontier hub; pointing DTS_EMULATOR_TASKHUB at it works only while no dev Host is attached, because DTS hands a run to any worker on its hub.

To check the packages from a consumer's point of view — restoring the real .nupkg files rather than project references:

dotnet pack FrontierPlatform.slnx -c Release -o ./artifacts
dotnet run -c Release --project samples/Frontier.Platform.SmokeConsumer

This is what catches a dependency missing from a nuspec or a type that is internal but needed — both of which pack perfectly happily. It runs on every PR as part of the pack job.

Contributing

Conventions live in .claude/skills/ and are summarised in CLAUDE.md. The short version:

  • Every public member must appear in that library's PublicAPI.Shipped.txt or PublicAPI.Unshipped.txt; the build fails otherwise.
  • Commit subjects are scope: Imperative summary, with scope!: marking a break to a package's public surface. CI validates this.
  • Architecture tests encode the severability guarantee. Never weaken one to make a build pass.

About

Reusable packaged libraries aligned to the Frontier Architecture

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages