Sovereign M⁸ — Build System

Audience: Engineers building, signing, and distributing Franklin.app.

Updated: 2026-05-05

---

Overview

The sovereign build system produces a single distributable artifact:

dist/Franklin.app          — sovereign macOS application (ad-hoc signed)
dist/GaiaFTCL-Sovereign-M8.dmg  — distributable disk image (~250 MB)

Franklin.app is the single sovereign entry point. VQbitVM and

FranklinConsciousnessService are bundled inside it as child processes.

They are not user-facing apps — they are subsystems owned by the

Franklin process on Franklin's internal NATS bus.

---

Scripts

scripts/build_sovereign.sh

Builds the full sovereign stack and packages the DMG.

bash scripts/build_sovereign.sh [--release|--debug]

Phase sequence:

1. swift build -c release — all three products (GaiaFTCLApp, VQbitVM, FranklinConsciousnessService)

2. swift test — GAMP 5 full qualification suite (≥155 tests required)

3. Assemble app bundle in /tmp (see codesign lesson below)

4. Strip iCloud xattrs (com.apple.FinderInfo, com.apple.fileprovider.fpfs#P)

5. Ad-hoc code sign with codesign --force --deep --sign -

6. Verify with codesign --verify --deep

7. ditto signed bundle to dist/Franklin.app

8. Create DMG with hdiutil create -format UDZO -imagekey zlib-level=9

9. Print machine-readable terminal line: CALORIE DMG created <path>

The last line CALORIE DMG created … is the gate read by sovereign_loop.sh.

scripts/sovereign_loop.sh

Autonomous overnight improvement driver. Runs build → test → DMG cycles

until CALORIE_THRESHOLD (default: 3) consecutive clean passes.

zsh scripts/sovereign_loop.sh            # runs until CALORIE
zsh scripts/sovereign_loop.sh --once     # single iteration then exit
zsh scripts/sovereign_loop.sh --no-dmg   # skip DMG (faster, debug only)

Status file written after every iteration:

logs/sovereign_loop/status.json

Terminal states:

• CURE — iteration passed, not yet at threshold
• CALORIE — consecutive_passes >= CALORIE_THRESHOLD — sovereign class fully instantiated
• BLOCKED — build or test failure; last_error field has the first 5 error lines

Healing loop: The loop never pauses between iterations. An external agent

(Claude overnight) reads status.json, fixes source, and the loop measures the

fix on the next iteration.

---

CALORIE Threshold

Three consecutive passes are required because:

• Pass 1 confirms the fix compiles and tests pass.
• Pass 2 confirms the fix is deterministic (not a fluke).
• Pass 3 confirms the DMG build is stable end-to-end.

A single pass is CURE. Three consecutive passes is CALORIE.

---

Codesign: The iCloud Detritus Problem

Symptom: codesign fails with:

Franklin.app: resource fork, Finder information, or similar detritus not allowed

Root cause: The project lives under iCloud Drive (File Provider scope). The OS

immediately re-adds com.apple.FinderInfo and com.apple.fileprovider.fpfs#P

extended attributes to any directory created in the project path. codesign

treats these as fatal detritus and refuses to sign.

Fix: Assemble the app bundle in /tmp (outside iCloud scope):

TMPBUILD=$(mktemp -d)           # /tmp/tmp.XXXXXX — outside iCloud scope
TMPAPP="$TMPBUILD/Franklin.app"
# ... copy executables, bundles, plist ...
# Strip any residual xattrs
find "$TMPAPP" -exec xattr -d com.apple.FinderInfo {} \; 2>/dev/null || true
find "$TMPAPP" -exec xattr -d "com.apple.fileprovider.fpfs#P" {} \; 2>/dev/null || true
# Sign in /tmp — xattr strips stick here
codesign --force --deep --sign - "$TMPAPP"
codesign --verify --deep "$TMPAPP"
# Now move to dist/
rm -rf "$DIST_DIR/Franklin.app"
ditto "$TMPAPP" "$DIST_DIR/Franklin.app"
rm -rf "$TMPBUILD"

Do not use --strict on the verify step. codesign --verify --deep --strict

rejects com.apple.macl (mandatory access control list) which is a system-managed

attribute added by the OS after signing. --verify --deep (without --strict)

is the correct gate.

---

BASH_SOURCE in zsh

build_sovereign.sh uses ${BASH_SOURCE[0]:-$0} to locate itself:

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"

sovereign_loop.sh is a zsh script that calls build_sovereign.sh via:

zsh scripts/build_sovereign.sh --debug

When a bash script is executed via zsh, BASH_SOURCE[0] is not set in

zsh's environment. The fallback :-$0 makes $0 the effective script path.

Without this fallback, SCRIPT_DIR resolves to the parent of scripts/ (the

cells directory) instead of cells/xcode, and all relative paths break silently.

---

App Bundle Layout

Franklin.app/
  Contents/
    MacOS/
      Franklin                ← main executable (GaiaFTCLApp product)
    Resources/
      bin/
        VQbitVM               ← sovereign child process
        FranklinConsciousnessService  ← sovereign child process
      *.bundle                ← Swift module resource bundles
    Info.plist
    PkgInfo                   ← "APPLGFTL"

Franklin owns the NATS bus on port 4222. VQbitVM and FranklinConsciousnessService

connect to it as child processes. There are no separate terminal windows.

One entry point: open Franklin.app.

---

Info.plist Key Values

LSMultipleInstancesProhibited prevents two Franklin instances fighting over

port 4222.

---

Build Matrix