Repository Public License
1# ORIX Convert — engine contract and working rules23Read this before touching the repository. It binds every engine, the core, the app and the documentation.45## What ORIX Convert is67A native macOS file-conversion studio (Swift 6, SwiftUI + AppKit), Apple Silicon only (arm64), macOS 15.0 minimum,8bundle id `ai.spboucher.orix.convert`, not sandboxed, Hardened Runtime, Developer ID + notarized.9Everything runs on the Mac: no network code, no API keys, no accounts, no telemetry.10Nothing may depend on software installed on the user's Mac (no Homebrew, Python, FFmpeg, LibreOffice, Pandoc lookups).1112## Repository layout1314```15Packages/ORIXConvertCore/ core: format catalog, engine protocol, detection, planner, queue, validation, history16Packages/Engine<Name>/ one Swift package per engine family (own Package.swift, depends on ../ORIXConvertCore)17EmbeddedEngines/<name>/ build.sh for each bundled third-party library (pinned version + SHA-256), LICENSE notes18EmbeddedEngines/tools/ bundled helper executables (ffmpeg, pandoc, LibreOffice.app…) — gitignored, built by scripts19App/ the SwiftUI/AppKit application20Tests/Fixtures/ shared fixtures (small; generated by code wherever possible)21docs/ research, compatibility matrix, architecture, security, release22```2324Each agent owns the directories named in its brief and must not edit files outside them, except where the brief25says so. `Packages/ORIXConvertCore/Sources/ConvertCore/{Formats,Engine,Tools}.swift` is the shared contract:26do not change existing declarations. If you truly need an addition (a new `FormatID`, a `Preserved` case, an27inspection field), make it purely additive and mention it in your final report.2829## The engine contract (`ConvertCore/Engine.swift`)3031- An engine is a `ConversionEngine`: `id`, `displayName`, `paths`, `options(for:)`, `inspect`, `preflight`,32 `convert`, `validate`.33- **A `ConversionPath` may be declared only if `convert` really implements it and a test converts a real fixture34 through it and checks the output.** No path may be listed "because the library should handle it".35 If a path works only on a narrow corpus, mark it `.experimental`. If it does not work, do not list it — document36 it as unsupported in your engine's notes instead.37- `fidelity`, `preserves` and `limitations` must be truthful. Limitations are shown to users before converting.38- `convert` writes only inside `context.workDirectory` (use `context.outputURL(for:)`), reports **measured**39 progress (`fraction: nil` when it cannot be measured — never a made-up fraction), calls40 `context.checkCancellation()` in loops, and emits `context.warn(...)` whenever data is dropped41 (alpha flattened, animation reduced to one frame, formulas dropped, styles lost, CRS assumptions…).42 **No silent data loss.**43- `validate` re-opens the output with an independent decoder where possible and checks concrete facts44 (dimensions, duration within tolerance, page/row/entry counts, geometry counts…).45- `inspect` returns only values actually read from the file. Unknown stays `nil`.46- Options are described by `OptionDescriptor`s so the app can build the settings UI generically. Use clear English47 labels; keep keys stable and lowercase-dotted (`quality`, `resize.width`, `metadata.strip`).48- Inputs are untrusted: bound memory and output size, reject absurd dimensions, never trust declared lengths,49 never execute macros/scripts from documents, never follow paths out of the work directory.50- Never use private Apple APIs. Never circumvent DRM or encryption (a password supplied by the user is fine).51- Helper executables are run only through `ProcessRunner` with `BundledTools.require(...)` — argument arrays,52 no shell, no PATH lookups.5354Each engine package exposes one public factory, e.g. `public func makeEngines() -> [any ConversionEngine]`55(module name = package name, e.g. `EngineImage`).5657## Third-party code5859- Allowed only if it is bundled, runs locally, builds for arm64 macOS 15+, and has a compatible license60 (BSD/MIT/Apache/zlib/MPL; LGPL as a replaceable dynamic library or separate executable; GPL only as a separate,61 unmodified executable run as its own process — and only if nothing permissive does the job).62- Every library gets `EmbeddedEngines/<name>/build.sh` (pinned version, SHA-256 of the download, reproducible,63 `MACOSX_DEPLOYMENT_TARGET=15.0`, arm64) and a `EmbeddedEngines/<name>/NOTICE.md` (name, version, URL, license,64 how it is linked, obligations). Static libraries are wrapped into an `.xcframework` consumed as a SwiftPM65 `binaryTarget` (see `~/Desktop/Cluster/apple/ORIXSheet/Scripts/fetch-duckdb.sh` for the pattern). Sources and66 build products are gitignored; the scripts and notices are committed.67- Pure-Swift SwiftPM dependencies are fine when justified (pin exact versions).68- Homebrew tools on this Mac (cmake, ninja, nasm if present…) may be used **to build**, never at run time.69 Do not `brew install` anything without saying so in your report.7071## Tests7273- Swift Testing (`import Testing`) in each package's test target. Fixtures are generated in code or by the74 bundled tools at test time when possible; small binary fixtures go in the package's `Tests/.../Fixtures`.75 Do not download test files from the internet at test time.76- Every declared path needs at least one test that converts and validates. Add tests for malformed input,77 cancellation, and data-loss warnings where relevant.78- Tests must pass with `swift test` run from the package directory. Use `--scratch-path` if you need isolation.79- End your work by writing `docs/compatibility/engines/<engine>.md`: a table of every declared path80 (source, destination, operation, status, fidelity, preserves, limitations, test name) plus measured performance81 numbers you actually ran, plus an explicit list of what was evaluated and NOT implemented, and why.8283## Honesty rules8485- Never invent a number, a test result, a format, a screenshot, a benchmark or a status.86- "Supported" means: implemented + tested + passing on this machine today.87- If something cannot be done properly, say so plainly in your report and in the docs.8889## Machine rules9091- This Mac is shared with other running sessions. **Never use `pkill -f`, `killall` or broad kills**; kill only92 PIDs you started. Do not drive the screen (no UI automation) unless your brief says so.93- The file `~/Desktop/Cluster/apple/CLAUDE.md` (KHAELOR) loads automatically here; it belongs to another project.94 Ignore it entirely.95- System language is French: pass `LC_ALL=C` to shell tools when parsing numbers.96- Do not run `git commit`, `git push` or anything on remote machines. The lead integrates and commits.97- Do not spawn sub-agents.98- Source file header (Swift):99 ```swift100 // ORIX Convert — <path from repo root>101 // Description: <one or two lines>102 // Author: Simon-Pierre Boucher — contact@spboucher.ai103 ```104 Shell/Python scripts use the same three lines with `#`.105- Swift 6 language mode, strict concurrency. No force-unwraps on untrusted data.106107## Final report (what the lead needs back)108109Short and factual: paths declared (count + list), test count and result (paste the summary line), libraries110bundled with sizes, anything additive you changed in the core contract, what is not implemented and why,111known defects.112