SPB Git

Repository Public License

ENGINE-CONTRACT.md 7.2 KB

# 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

text
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, release

Each 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 ConversionPath may be declared only if convert really 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, preserves and limitations must be truthful. Limitations are shown to users before converting.
  • convert writes only inside context.workDirectory (use context.outputURL(for:)), reports measured progress (fraction: nil when it cannot be measured — never a made-up fraction), calls context.checkCancellation() in loops, and emits context.warn(...) whenever data is dropped (alpha flattened, animation reduced to one frame, formulas dropped, styles lost, CRS assumptions…). No silent data loss.
  • validate re-opens the output with an independent decoder where possible and checks concrete facts (dimensions, duration within tolerance, page/row/entry counts, geometry counts…).
  • inspect returns only values actually read from the file. Unknown stays nil.
  • 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 ProcessRunner with BundledTools.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 a EmbeddedEngines/<name>/NOTICE.md (name, version, URL, license, how it is linked, obligations). Static libraries are wrapped into an .xcframework consumed as a SwiftPM binaryTarget (see ~/Desktop/Cluster/apple/ORIXSheet/Scripts/fetch-duckdb.sh for 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 install anything 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's Tests/.../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 test run from the package directory. Use --scratch-path if 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, killall or 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=C to shell tools when parsing numbers.
  • Do not run git commit, git push or anything on remote machines. The lead integrates and commits.
  • Do not spawn sub-agents.
  • Source file header (Swift):
    swift
    // ORIX Convert — <path from repo root>
    // Description: <one or two lines>
    // Author: Simon-Pierre Boucher — contact@spboucher.ai
    Shell/Python scripts use the same three lines with #.
  • 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.

Files main
Menu

Theme