Skip to main content

Call the existing engine

The command-line executable and C ABI call the same Rust dispatcher. Swift's NativePlanningEngine owns the JSON transport, ABI check, response decoding and buffer release. The host schedules computation away from its UI actor and captures immutable inputs first.

Operations​

CLIC operationInputResult
validate1IntentValidity receipt or rejection
prepare-key2Intent, leg ID, revisions, resourcesNative dependency key
evaluate3Intent, job with key, resourcesResult with component states
edit-mapping4Intent, accepted result, context; retained sources for reuseCaptured point/edge ownership
reuse5Current intent/job/resources, original admitted sourceCurrent result with reuse proof
publish6Intent, current dependencies, admitted results, context and publication IDsMatched snapshot and draw
resolve7Intent, job with key, resourcesGeometry with evaluation pending
map-edit8Current intent/result/context and captured commandNew intent or rejection
capture-resources9Host-acquired resource objectResources with native identities
check-support10IntentSubmission/structural support receipt

The CLI accepts one JSON value from a file or stdin, bounded to 16 MiB. Success prints a JSON value and exits zero; rejection writes a diagnostic to stderr and exits nonzero. A successful evaluation response may still contain unavailable components: inspect state.

Swift bridge example​

This is the existing compiled bridge test, included from its owner. Its @testable import and fixture lookup are test-harness details, not a published package installation recipe. The important call is NativePlanningEngine.execute(.validate, request:as:); production hosts can also use validateIntent(_:).

// NativePlanningEngineTests.swift: exercise errors through the actual C ABI.
// OpenAI Codex as Directed by Tyson Weihs.
import Foundation
import Testing
@testable import AeronauticPlanningNative

@Suite struct NativePlanningEngineTests {
private struct Validation: Decodable, Sendable { let valid: Bool }

@Test func acceptsTheCanonicalPortableFixture() throws {
var root = URL(fileURLWithPath: #filePath)
for _ in 0..<7 { root.deleteLastPathComponent() }
let input = root.appendingPathComponent("modules/planning/schema/v1/intent/fixtures/valid/minimal-direct.json")
let result = try NativePlanningEngine.execute(.validate, request: Data(contentsOf: input), as: Validation.self)
#expect(result.valid)
}

@Test func rejectsAmbiguousInput() throws {
do {
_ = try NativePlanningEngine.execute(.validate, request: Data(#"{"x":1,"x":2}"#.utf8), as: Validation.self)
Issue.record("Duplicate fields must fail before intent admission")
} catch let error as NativePlanningError {
#expect(error.code == "rejected")
#expect(error.message.contains("duplicate"))
}
}

@Test func rejectsEmptyBuffer() throws {
do {
_ = try NativePlanningEngine.execute(.validate, request: Data(), as: Validation.self)
Issue.record("Empty request must be rejected")
} catch let error as NativePlanningError {
#expect(error.code == "invalidRequest")
}
}
}

Internal services and server adapters​

A server can invoke the CLI or bind the C ABI using the same request contract. Give each job its own immutable capture and retain the exact trusted dependency key for admission. Do not accept host filesystem paths or native handles from an untrusted client. Resource acquisition, authorization, cancellation and request limits belong to the server boundary.

This reference does not advertise a public HTTP planning endpoint or a generated JavaScript SDK. Existing Router, weather and MCP APIs remain owned by their services. A new transport adapter needs its own route, authentication and conformance tests before it becomes a supported client integration.

See version compatibility and downloadable schemas.