Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agents/skills/journal-build/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,10 @@ description: Build and verify Journal Apple apps for macOS, iOS Simulator and iP
Run `bash .agents/skills/journal-build/scripts/build_journal_apple.sh --help` from the repository root. Maintained build, CI provisioning, icon packaging and probe-assembly helpers live in `scripts/`; product acceptance tools remain in `tool/`. The Apple entry point never installs apps, updates dependencies/pins, touches graphs or deletes caches. Coordinate CPU/actool, switch locks and borrowed inputs with active owners.

- Before choosing a target or building, read [targets and prerequisites](references/targets.md). macOS requires an explicit prepared locked switch. Simulator stubs require `--link-only`; runtime imports and device builds require explicit experimental provenance. All current targets are ARM64 with deployment target >=26.0.
- For Simulator producer evidence, use `macos --producer-only --switch ...` with the same prepared inputs. It stops after native production and final input checks, returns a schema-2 envelope and `status: native-produced`, and does not build an App. Then pass that envelope to the normal explicit Simulator importer.
- For `--experimental-host-restamp --native-manifest`, read [native provenance](references/native-provenance.md). Original producer records remain immutable. Host restamping does not prove full iOS cross-compilation or ABI acceptance.
- For incremental reuse, switch/cache mismatch, CI changes or cold/hot measurements, read [cache and CI](references/cache-and-ci.md). Reuse existing input manifests; do not relocate switches, mix target objects, change another owner's pins, or skip locked-dependency and final source/build/test checks to obtain a hit. GitHub cache lifecycle stays in the workflow and CI dependency preparer.

Only `status: built` confirms an artifact. `preflight-passed` and `link-only` are not runtime acceptance. Preserve `cross_abi_validated=false` for host-restamped objects and hand off the manifest with the app. Installation and phone/graph operations require their own scope.
Only `status: built` confirms an App. `preflight-passed` and `link-only` are not runtime acceptance. Preserve `cross_abi_validated=false` for host-restamped objects and hand off the manifest with the app. Installation and phone/graph operations require their own scope.

For build-tool changes run `PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/journal-build/scripts/test_journal_build.py`. Use `scripts/test_apple_app_icon.py` when packaging changes and the owner/environment permit actool; use `sh test/test_native_static_gmp.sh .agents/skills/journal-build/scripts/native_static_link_flags.sh` for static-link helper changes. A layout-only move needs path/import and Dune resource checks, not a new production build or GUI run.
4 changes: 3 additions & 1 deletion .agents/skills/journal-build/references/cache-and-ci.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Cache, recovery and CI measurement


Identity includes source, actual dependency ABI inputs, toolchain/SDK, flags and target. Identical inputs reuse incremental state; changed inputs select another namespace. Every run leaves external phase logs and `run-*/manifest.json`. The cache has a nonblocking lock; native Dune builds also hold the switch read lock. A busy lock belongs to its active owner: coordinate or wait. Preserve existing output/rollback apps and choose a new `--app-dir`; nothing is cleared automatically.
Identity includes source, actual dependency ABI inputs, toolchain/SDK, flags and target. Identical inputs reuse incremental state; changed inputs select another namespace. Native runs preserve a Dune process trace for actual compile/link observations. Every run leaves external phase logs and `run-*/manifest.json`. The cache has a nonblocking lock; native Dune builds also hold the switch read lock. A busy lock belongs to its active owner: coordinate or wait. Preserve existing output/rollback apps and choose a new `--app-dir`; nothing is cleared automatically.

Producer-only and the native macOS App path share native incremental state for identical inputs. A warm producer reads the current Dune rule and revalidates the immutable evidence and live inputs before reuse; an existing cache directory alone is not a hit. Keep measurements on one source revision, explicit switch/compiler/SDK, configuration and absolute paths. For a cold sample, use a new owned external cache; never clean shared dependencies. Record actual compiler/link actions and separate phase/end-to-end elapsed time from resource or authorization waits. A failed macOS App attempt is not a successful App baseline: report its failed phase separately and compare final Simulator success only when both routes reach it.

For failure, read `failed_phase`, `error` and that phase's log. Correct target/environment or select matching prepared inputs. Source/configuration/pin/current-input mismatch requires matching provenance; a historical archive change alone can use the validated receipt contract above. Missing runtime/mldoc or unresolved XMLm references require linker-rule review. Schema 2 permits an unused XMLm unit to be omitted while retaining strict locked input identity; schema 1 keeps its original force-link checks. Protected Dune/spec/lock edits still follow the repository's authorization rules. Legacy object-injecting Dune aliases remain refused; probe helpers use the isolated mode above.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ compiler, pins, target C and complete-object identities retain the checks below.
The link record adds an absolute `working_directory` and records the actual,
expanded `-output-complete-obj` argv, including its output. Every explicit native
input and its `.a`/`.o` companion must occur by absolute path in `direct_native_input_sha256`.
Both original mldoc and XMLm archives must occur in that argv with the recorded
The maintained producer also binds the runtime headers at production time, so a first target import rejects header changes after handoff. Both original mldoc and XMLm archives must occur in that argv with the recorded
archive hash; response-file commands and output-as-input identities are refused.
Recorded argv is inspected as data, never executed by the importer.

Expand Down
15 changes: 14 additions & 1 deletion .agents/skills/journal-build/references/targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,24 @@ bash .agents/skills/journal-build/scripts/build_journal_apple.sh ios-device --ex
--sign-entitlements /path/to/device.entitlements --build-number 1.2.3
```

To produce native evidence without an unrelated macOS App build:

```sh
bash .agents/skills/journal-build/scripts/build_journal_apple.sh macos --producer-only \
--switch YOUR_SWITCH --lui-package /path/to/lui/platform/apple --cache-dir ../journal-build-cache
# Use the printed native-input.json path; keep its immutable source/link records and object.
bash .agents/skills/journal-build/scripts/build_journal_apple.sh ios-simulator \
--experimental-host-restamp --native-manifest /printed/path/native-input.json \
--lui-package /path/to/lui/platform/apple --cache-dir ../journal-build-cache
```

`--producer-only` requires native macOS inputs and rejects App output/signing modes. It keeps cache/switch locks, locked preflight, real Dune rule/input identity, original dependency bytes, runtime/mldoc and final source/compiler/dependency revalidation. It does not run macOS Swift, icons, packaging or signing. `status: native-produced` confirms only the host object and schema-2 producer evidence; it cannot be used as `validated_build` to make inputs historical. The target Simulator build still performs target C, Swift, final provider/platform checks and signing. Host restamping remains experimental with `cross_abi_validated=false`.

`--preflight` checks without compilation; remove it for the macOS build. Unset ambient compiler/OCaml/SDK lookup overrides; SDK selection is explicit. Pins come from active switch state; raw source metadata may omit `url`, while any recorded installed source must still agree. CI local pins require their matching resolution record and clean resolved commit. Provision dependencies separately with `.agents/skills/journal-build/scripts/prepare_ci_dependencies.py`, which fetches and pins; use only an authorized switch. The builder never repairs it implicitly. Offline moving refs have no remote freshness claim.

## Accept and hand off


Only `status: built` confirms an artifact. Check recorded revisions/dirty hashes, target/SDK/flags, bundle/executable hashes, version and signing identity. Resources/icons precede signing; device profile/certificate/team/entitlements and strict signature are checked. Current GMP archives are rehashed before native macOS acceptance. Experimental builds additionally check Swift object platforms, fresh target C link-map providers and runtime/mldoc retention. Record XMLm's actual retention separately from its locked input identity: schema 2 allows its unused unit to be omitted and rejects unresolved references; legacy schema 1 still requires its force-link proof and retention. Listing a `.cmxa` alone does not establish retention.
Only `status: built` confirms an App. Check recorded revisions/dirty hashes, target/SDK/flags, bundle/executable hashes, version and signing identity. Resources/icons precede signing; device profile/certificate/team/entitlements and strict signature are checked. Current GMP archives are rehashed before native macOS acceptance. Experimental builds additionally check Swift object platforms, fresh target C link-map providers and runtime/mldoc retention. Record XMLm's actual retention separately from its locked input identity: schema 2 allows its unused unit to be omitted and rejects unresolved references; legacy schema 1 still requires its force-link proof and retention. Listing a `.cmxa` alone does not establish retention.

`preflight-passed` and `link-only` are not runtime acceptance. Preserve `cross_abi_validated=false` for host-restamped objects and state which compilation was reused. Carry the manifest with the App; installation and phone/graph operations are separate from build. For builder changes, use `PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/journal-build/scripts/test_journal_build.py` and the existing icon test as appropriate.
Loading
Loading