Patch format

A patch is one JSON file with two nested layers. Both are checked in full before anything is applied, and an envelope that does not match is refused rather than partially landed.

Write the file, then hand it to your operator. It goes into their Downloads folder, where the connector notices it within a few seconds.

The envelope


{
  "schema": "LLAMBDA_DOWNLOAD_PATCH_V1",
  "interaction_id": "<your interaction id>",
  "patch_id": "<unique per patch>",
  "authorization": "<token>",
  "target": {
    "collection": "work",
    "gizmo": "<gizmo>",
    "gadget": "<gadget>",
    "agent": "<your name>"
  },
  "patch": {
    "format": "LS_FORK_JSON_PATCH_V1",
    "agent": "<your name>",
    "title": "<one line>",
    "files": [
      { "op": "upsert", "path": "<collection-relative>", "content": "<whole file>" }
    ]
  }
}

Rules that cost a round when broken

interaction_id is not the token: Both are checked, and they are checked together. A correct token with an unfilled placeholder id fails exactly like a wrong token, so resealing the token never helps. Fill in the id.
Every file entry needs op: Either upsert or delete. Nothing else is accepted, and an entry without one is rejected before the rest of the envelope is read.
Paths are relative to the collection root: Not to the gadget. A file in the paint gadget starts paint.gizmo/paint.wires/. Forward slashes only: a path containing a backslash or a colon is refused, as is one that is absolute or that contains a . or .. segment.
content is the whole file: Not a diff, and not a fragment. delete entries carry no content.
patch_id must be new each time: Reusing one is how a corrected patch gets mistaken for the patch it corrects, and the second one is then ignored as already seen.
No extra top-level fields: Unknown fields are refused by name. The refusal reads as though the whole patch is wrong, when usually one field is misspelled or one layer is missing its wrapper.
semantic is optional: It names the kind of edit, for a person and for Elliot's templates. The lander does not read it, so leaving it out is fine and including it is accepted.

Limits

At most 200 file entries in one patch.
Each path at most 512 characters.
The authorization token between 32 and 256 characters.
Collection, gizmo, gadget, agent, interaction id and patch id are symbolic names: letters, digits, dash and underscore.

Adding a Haskell module

The build is descriptor-driven. A module that is not declared will compile on your machine and fail in the collection, so a patch adding one must also patch package.nut — the module under exposes:, and any new package under depends:. Do not patch the generated .cabal file: it is written by wires cast from package.nut, and a hand-edited one is skipped by the generator from then on.

What comes back

land_ok: false: It never landed. The patch did not apply, the target was wrong, or the envelope was malformed. Nothing was built, so there are no compiler diagnostics to read.
land_ok: true, build_ok: false: It landed and would not compile. Read diagnostics; they are the compiler's own words, capped at the first ten useful lines.
ok: true: Landed and built. Carry on.