oka_conformance library

Shared publish-target conformance suite for oka (ADR-0014).

The reusable test harness every oka target package imports from its tests — the universal_storage_conformance pattern applied to oka publishing:

import 'package:oka_conformance/oka_conformance.dart';

test('publish-play conforms (ADR-0014)', () async {
  await expectPublishConformance(
    const PlayPublishTarget(),
    ctx,
    sourcePaths: [p.absolute('lib/src')],
  );
});

The three laws (ADR-0014):

Dry-run without credentials succeeds and produces a PublishPlan describing exactly what a real run would do — assert its shape with expectPlanShape / expectPlanDescribes.
No stdin, ever — enforced by expectPublishConformance over sourcePaths.
No secret values in state, logs, or events — assert over any dumped text with expectNoSecretMaterial / expectStateRedacted, and prove zero HTTP with FakeHttpTransport.assertNoRequests.

FakeHttpTransport is the offline transport for the real-run tests: fully scripted, recording, and throwing on unexpected requests — tests stay offline by construction.

Classes

Artifact<T>: A typed artifact key exchanged between pipeline steps (ADR-0006).
BuildContext: Typed build context passed to every BuildStep (ADR-0006).
BuildStep: A composable unit of the build pipeline (ADR-0006).
CredentialRef: A typed path reference to a build-host credential file (ADR-0014).
CredentialResolution: Result of credential-path resolution: the resolved path plus every candidate tried in order (the remediation law — failures name what was tried and the fix).
CredentialResolver: Credential-path resolution policy as data (ADR-0014).
CredentialSource: One ordered candidate source inside the credential-path policy.
FakeHttpTransport: A scripted, recording http.Client — the offline transport for any target-package test (ADR-0014 conformance: no real network, ever).
HostProcessLiveness: Default ProcessLiveness: ps / kill -0 on macOS, /proc/<pid> on Linux, and Windows PowerShell/CIM with machine and boot identity on Windows.
Pipeline: Runs a list of steps in order, stopping at the first failure.
PipelineState: Mutable state shared across pipeline steps.
ProcessLiveness: Platform liveness / identity / kill seam (ADR-0018 §1): the three members every kind-specific lifecycle logic needs, abstracted from the host OS.
PublishPlan: The dry-run publish plan: exactly what a real run would do — the ADR-0008 plan law applied to publishing (ADR-0014).
PublishPlanStep: The plan-producing tail step oka_core substitutes for the upload step in dry-run mode (ADR-0014 dry-run law, as code).
PublishTarget: A Target with publishing conformance laws as code (ADR-0014).
RecordedRequest: One request recorded by a FakeHttpTransport.
ScriptedResponse: A scripted reply: status, headers, and body bytes.
SessionStateCleanupStep<H>: Cleanup preparation phase. Filesystem deletion remains core-owned.
SessionStateContext<H>: Typed input shared by workflow phases.
SessionStateFinding: One human- and machine-readable safety observation.
SessionStateInspector<H>: Read-only activity and ownership evidence.
SessionStateLease: A versioned durable pointer to one state resource.
SessionStateManager: Executes a workflow's typed provision stages after a durable reservation.
SessionStatePlan<H>: Typed planning value. handle is kept in memory and never serialized.
SessionStatePlanner<H>: Produces a plan without creating or mutating a resource.
SessionStateProvisionStep<H>: One idempotent provisioning phase.
SessionStateReconciler: Reconciles only when an explicit workflow with the exact recorded version is composed. Unknown providers and any inconclusive evidence are retained.
SessionStateReconcileReport: Full reconcile report, including registry parse issues.
SessionStateRegistry: Durable state records stored outside a project's .oka_cache.
SessionStateRegistryIssue: One session-state registry parse or filesystem issue.
SessionStateRequest: Inputs to a pure planner.
SessionStateSource<H>: A read-only source for reconstructing a typed handle from a durable lease.
SessionStateWorkflow<H>: Immutable composition of plan, typed source, provision, inspection and cleanup components. id is a stable, globally unique provider identifier; packages and projects must not reuse another workflow's ID because out-of-project CLI fallback can only compose first-party workflows.
StepResult: The outcome of a single pipeline step.

Enums

BuildMode: Build mode enumeration.
CredentialSourceKind: Where a credential path may come from, in descending order of preference (mirrors ToolSourceKind from the T1 tool policy).
LeaseScope: Lifecycle scope of a leased process (ADR-0018 §3): declared on the spawn target — a parameter, not a type hierarchy.
SessionStateAcquisitionMode: How this acquisition relates to the resource.
SessionStateDisposition: Classification for a session-state lease.
SessionStateNamespace: Whether a resource is project-local or shared by the host.
SessionStateOwnership: Who owns the state resource itself, not the process using it.
SessionStatePhase: Durable lifecycle phase.
SessionStateResourceKind: A filesystem tree Oka can manage, or a resource that needs its own API.
SessionStateRetention: How long state is retained independently of its owning process.
SessionStateUse: Structured result from one state inspector. Only unused is affirmative; busy and unknown both block cleanup.

Extension Types

OkaConfig: Extension type that represents the main Oka configuration.

Constants

secretishKeyPatterns → const List<String>: Secret-ish dart-define key patterns (ADR-0014).

Functions

auditPublishConformance(PublishTarget target, BuildContext ctx, {List<String> sourcePaths = const []}) → Future<List<String>>: Audits a PublishTarget against the three publishing conformance laws (ADR-0014) and returns human-readable violations (empty = conforming).
describeTarget(Target target, BuildContext ctx) → TargetChainDescription: Describes target's compiled step chain without running it (ADR-0015).
expectNoSecretMaterial(String output, {Iterable<CredentialRef> refs = const [], Iterable<Pattern> forbidden = const [], String context = 'output'}) → void: Asserts output — any dumped text a target produces: a PipelineState snapshot, log lines, a PublishPlan rendering, step result data, recorded request headers — contains no secret material (ADR-0014 law 3, as a reusable assertion):
expectPlanDescribes(PublishPlan plan, List<String> fragments) → void: Asserts the plan renders as describable text (the agent-facing law): every listed fragment must appear in plan.describeLines().
expectPlanShape(PublishPlan plan, {String? target, String? endpoint, String? track, String? artifactId, String? artifactPath, bool? dryRun, Map<String, String> metadata = const {}, bool exactMetadata = false, List<CredentialRef>? credentials}) → void: Asserts the shape of a dry-run PublishPlan (ADR-0014 law 1): the plan must name the endpoint, track, artifact id/path, and every piece of non-secret metadata a real run would use — no more, no less.
expectPublishConformance(PublishTarget target, BuildContext ctx, {List<String> sourcePaths = const []}) → Future<void>: Asserts the three ADR-0014 publishing conformance laws for target — the shared suite any publish target must pass (the exportable seam target packages call from their tests).
expectSessionStateBorrowedRetention<H>({required SessionStateWorkflow<H> workflow, required SessionStateRequest request, required SessionStateRegistry registry, ProcessLiveness liveness = const HostProcessLiveness()}) → Future<SessionStateLease>: Acquires a caller-owned borrowed resource and proves explicit cleanup retains both its lease and (for directory resources) the caller's directory, independent of its retention duration.
expectSessionStateFailClosed({required SessionStateReconciler reconciler, required SessionStateRegistry registry, required String leaseId}) → Future<SessionStateReconcileReport>: Confirms that a workflow's busy/unknown provider observation prevents explicit cleanup from disposing its lease.
expectSessionStateProvisionConformance<H>({required SessionStateWorkflow<H> workflow, required SessionStateRequest request, required SessionStateRegistry registry, ProcessLiveness liveness = const HostProcessLiveness()}) → Future<SessionStateLease>: Checks workflow validation and proves that each provider provision stage starts only after its lease and reservation marker are durable.
expectSessionStateRegistryIssues(SessionStateRegistry registry) → Future<List<SessionStateRegistryIssue>>: Returns registry issues, failing if the snapshot silently hides invalid or future-schema records.
expectStateRedacted(PipelineState state, {Iterable<CredentialRef> refs = const [], Iterable<Pattern> forbidden = const [], String context = 'PipelineState snapshot'}) → void: Asserts a full PipelineState carries no secret material and respects the ADR-0014 value-type law (refs, booleans, numbers, plans, path/id strings only) — usable on real-run states too, where auditPublishConformance (dry-run only) does not reach.
isSecretishKey(String key) → bool: Whether a dart-define key is secret-ish (case-insensitive match against secretishKeyPatterns).
validateTargetName(String name, {Set<String> reserved = reservedCliVerbs}) → String?: Validates a target name (ADR-0015).

Typedefs

FakeRouteHandler = ScriptedResponse Function(RecordedRequest request): Handler for one routed request.

Exceptions / Errors

CredentialResolutionException: Thrown when a required credential path fails to resolve. Names every candidate tried and the fix — same remediation law as ToolchainException.
PlanShapeException: Thrown by expectPlanShape when a dry-run plan does not describe exactly what a real run would do.
PublishConformanceException: Thrown by expectPublishConformance when a publish target violates an ADR-0014 conformance law. Escaping a test, this fails it with the full violation list — no test-framework dependency needed in oka_core.
SecretMaterialException: Thrown by expectNoSecretMaterial when dumped text (state, logs, plans, events, request dumps) contains secret material.
SessionStateConformanceException: A managed-session-state conformance assertion failed.
SessionStateRegistryException: Error from a state registry operation. Messages are safe to show in CLI.

oka_conformance library

Classes

Enums

Extension Types

Constants

Functions

Typedefs

Exceptions / Errors

oka_conformance package

oka_conformance library