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
2 changes: 1 addition & 1 deletion .agents/skills/journal-build/references/cache-and-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

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.

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 mldoc/XMLm retention requires linker-rule review; 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.
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.

## Reuse dependency and build state

Expand Down
64 changes: 64 additions & 0 deletions .agents/skills/journal-build/references/native-provenance.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,69 @@
# Experimental native provenance

Input identity and retained code are separate checks. Journal's Markdown path
requires the OCaml runtime and mldoc. XMLm is a locked dependency used by mldoc's
OPML units; an unused XMLm unit may be removed by the OCaml linker. Any unresolved
XMLm reference is rejected. No application anchor or global `-linkall` is needed.

## Ordinary archive inputs (schema 2)

New producers use `schema_version: 2`, with hash-bound `source` and `link` records
and optional `validated_build`. They do not supply `xmlm_force_link`. Source,
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
archive hash; response-file commands and output-as-input identities are refused.
Recorded argv is inspected as data, never executed by the importer.

Schema 2 supports the object-only Dune link form: the fixed code-generation
switches, `-w`/`-warn-error` values (including `@` warning sets), `-I`, `-o`, and
`-cclib` with one unquoted token naming an explicit bound archive/object or `-L`
directory; whitespace, quotes and backslashes in that value are refused because
OCaml can split it into additional linker arguments. Source files,
plugins, response files, `-l` providers, `-ccopt` and other unrecognized options
are refused rather than treated as proved inputs. Relative argv paths resolve
through the recorded working directory for every later archive/stub check.
Companion and dependency hash claims must agree; merging records cannot replace
a conflicting actual-input digest.

Recorded absolute input names use lexical normalization without resolving
symlinks and cannot contain `..`. First import hashes the current files through
those names. Receipt reuse retains the same recorded names even when historical
installation symlinks or their targets later disappear or change.

Each `new_dependency_provenance` entry for mldoc/XMLm retains `pinned_commit`,
`installed_archive`, archive/static archive hashes and installed source hashes.
It additionally supplies:

```json
{
"source_checkout": "/absolute/clean/pinned/checkout",
"original_unit": {"cmx_sha256": "SHA256", "object_sha256": "SHA256"},
"installed_sources_matched_to_pinned_git": {
"xmlm.ml": {"sha256": "SHA256", "git_path": "src/xmlm.ml"}
}
}
```

First import checks the clean checkout's exact pinned commit, hashes its raw Git
source blobs against the installed source records, and verifies the original
cmx and archive object member. Installation paths and Git paths remain inside
their respective roots. The immutable complete object's defined and undefined
symbols are inspected separately. `ocaml_units` records actual booleans for
`runtime`, `mldoc` and `xmlm`; runtime/mldoc must be present, XMLm may be absent.

A schema-2 receipt records `ocaml_units` in its imported dependencies and final
`production_link`, without the legacy `runtime_mldoc_xmlm_retained` flag. Those
observations must agree with each other and the still-present fixed host object.
Original source/archive/compiler input hashes may become historical only after
that successful hash-bound receipt, while current native source, object, runtime
headers, original evidence and SDK/signing checks remain live. A schema-1 receipt
cannot authorize schema 2, or vice versa.

## Legacy single-unit force link (schema 1)

The envelope references original producer records by SHA-256; paths are relative to the envelope, while producer records retain their own explicit paths:

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/journal-build/references/targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,6 @@ bash .agents/skills/journal-build/scripts/build_journal_apple.sh ios-device --ex
## 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/XMLm retention. Listing a `.cmxa` alone does not establish retention.
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.

`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