ORIX Convert — engine contract and working rules
Read this before touching the repository. It binds every engine, the core, the app and the documentation.
What ORIX Convert is
A native macOS file-conversion studio (Swift 6, SwiftUI + AppKit), Apple Silicon only (arm64), macOS 15.0 minimum,
bundle id ai.spboucher.orix.convert, not sandboxed, Hardened Runtime, Developer ID + notarized.
Everything runs on the Mac: no network code, no API keys, no accounts, no telemetry.
Nothing may depend on software installed on the user's Mac (no Homebrew, Python, FFmpeg, LibreOffice, Pandoc lookups).
Repository layout
Packages/ORIXConvertCore/ core: format catalog, engine protocol, detection, planner, queue, validation, history
Packages/Engine<Name>/ one Swift package per engine family (own Package.swift, depends on ../ORIXConvertCore)
EmbeddedEngines/<name>/ build.sh for each bundled third-party library (pinned version + SHA-256), LICENSE notes
EmbeddedEngines/tools/ bundled helper executables (ffmpeg, pandoc, LibreOffice.app…) — gitignored, built by scripts
App/ the SwiftUI/AppKit application
Tests/Fixtures/ shared fixtures (small; generated by code wherever possible)
docs/ research, compatibility matrix, architecture, security, releaseEach agent owns the directories named in its brief and must not edit files outside them, except where the brief
says so. Packages/ORIXConvertCore/Sources/ConvertCore/{Formats,Engine,Tools}.swift is the shared contract:
do not change existing declarations. If you truly need an addition (a new FormatID, a Preserved case, an
inspection field), make it purely additive and mention it in your final report.
The engine contract (ConvertCore/Engine.swift)
- An engine is a
ConversionEngine:id,displayName,paths,options(for:),inspect,preflight,convert,validate. - A
ConversionPathmay be declared only ifconvertreally implements it and a test converts a real fixture through it and checks the output. No path may be listed "because the library should handle it". If a path works only on a narrow corpus, mark it.experimental. If it does not work, do not list it — document it as unsupported in your engine's notes instead. fidelity,preservesandlimitationsmust be truthful. Limitations are shown to users before converting.convertwrites only insidecontext.workDirectory(usecontext.outputURL(for:)), reports measured progress (fraction: nilwhen it cannot be measured — never a made-up fraction), callscontext.checkCancellation()in loops, and emitscontext.warn(...)whenever data is dropped (alpha flattened, animation reduced to one frame, formulas dropped, styles lost, CRS assumptions…). No silent data loss.validatere-opens the output with an independent decoder where possible and checks concrete facts (dimensions, duration within tolerance, page/row/entry counts, geometry counts…).inspectreturns only values actually read from the file. Unknown staysnil.- Options are described by
OptionDescriptors so the app can build the settings UI generically. Use clear English labels; keep keys stable and lowercase-dotted (quality,resize.width,metadata.strip). - Inputs are untrusted: bound memory and output size, reject absurd dimensions, never trust declared lengths, never execute macros/scripts from documents, never follow paths out of the work directory.
- Never use private Apple APIs. Never circumvent DRM or encryption (a password supplied by the user is fine).
- Helper executables are run only through
ProcessRunnerwithBundledTools.require(...)— argument arrays, no shell, no PATH lookups.
Each engine package exposes one public factory, e.g. public func makeEngines() -> [any ConversionEngine]
(module name = package name, e.g. EngineImage).
Third-party code
- Allowed only if it is bundled, runs locally, builds for arm64 macOS 15+, and has a compatible license (BSD/MIT/Apache/zlib/MPL; LGPL as a replaceable dynamic library or separate executable; GPL only as a separate, unmodified executable run as its own process — and only if nothing permissive does the job).
- Every library gets
EmbeddedEngines/<name>/build.sh(pinned version, SHA-256 of the download, reproducible,MACOSX_DEPLOYMENT_TARGET=15.0, arm64) and aEmbeddedEngines/<name>/NOTICE.md(name, version, URL, license, how it is linked, obligations). Static libraries are wrapped into an.xcframeworkconsumed as a SwiftPMbinaryTarget(see~/Desktop/Cluster/apple/ORIXSheet/Scripts/fetch-duckdb.shfor the pattern). Sources and build products are gitignored; the scripts and notices are committed. - Pure-Swift SwiftPM dependencies are fine when justified (pin exact versions).
- Homebrew tools on this Mac (cmake, ninja, nasm if present…) may be used to build, never at run time.
Do not
brew installanything without saying so in your report.
Tests
- Swift Testing (
import Testing) in each package's test target. Fixtures are generated in code or by the bundled tools at test time when possible; small binary fixtures go in the package'sTests/.../Fixtures. Do not download test files from the internet at test time. - Every declared path needs at least one test that converts and validates. Add tests for malformed input, cancellation, and data-loss warnings where relevant.
- Tests must pass with
swift testrun from the package directory. Use--scratch-pathif you need isolation. - End your work by writing
docs/compatibility/engines/<engine>.md: a table of every declared path (source, destination, operation, status, fidelity, preserves, limitations, test name) plus measured performance numbers you actually ran, plus an explicit list of what was evaluated and NOT implemented, and why.
Honesty rules
- Never invent a number, a test result, a format, a screenshot, a benchmark or a status.
- "Supported" means: implemented + tested + passing on this machine today.
- If something cannot be done properly, say so plainly in your report and in the docs.
Machine rules
- This Mac is shared with other running sessions. Never use
pkill -f,killallor broad kills; kill only PIDs you started. Do not drive the screen (no UI automation) unless your brief says so. - The file
~/Desktop/Cluster/apple/CLAUDE.md(KHAELOR) loads automatically here; it belongs to another project. Ignore it entirely. - System language is French: pass
LC_ALL=Cto shell tools when parsing numbers. - Do not run
git commit,git pushor anything on remote machines. The lead integrates and commits. - Do not spawn sub-agents.
- Source file header (Swift):Shell/Python scripts use the same three lines withswift
// ORIX Convert — <path from repo root> // Description: <one or two lines> // Author: Simon-Pierre Boucher — contact@spboucher.ai#. - Swift 6 language mode, strict concurrency. No force-unwraps on untrusted data.
Final report (what the lead needs back)
Short and factual: paths declared (count + list), test count and result (paste the summary line), libraries bundled with sizes, anything additive you changed in the core contract, what is not implemented and why, known defects.