From e258381f16a74a79bf8010389e19f0ac4545b758 Mon Sep 17 00:00:00 2001 From: "@permadeath.com" Date: Thu, 20 Aug 2026 16:53:21 -0400 Subject: [PATCH] docs(match-records): put artifacts/ in the tree, and the inputs above it A listing of a real match showed two things the tree did not: every key arena writes sits under matches//artifacts/, and the manifest and staged camo sit above it, because headquarters writes those before the container exists. Co-Authored-By: Claude Opus 5 (1M context) --- docs/match-artifacts.md | 73 ++++++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 26 deletions(-) diff --git a/docs/match-artifacts.md b/docs/match-artifacts.md index c6abf50..65e8329 100644 --- a/docs/match-artifacts.md +++ b/docs/match-artifacts.md @@ -24,11 +24,12 @@ after it. Every artifact a match emits: which process writes it, where it lives in the container, and which prefix it lands in. -**This draws the layout this document proposes, not the one running today.** The -prefixes are `launch/ raw/ derived/ diagnostics/`; today they are +**This draws the layout, which is now what runs.** Boxes still marked "new" +are the ones that changed from what came before it — the prefixes were `result.json turns/ shots/ diagnostics/`, and four artifacts drawn as collected -here are currently deleted. Where the two differ, a box says so. The tables -below are the as-is inventory. +here used to be deleted. A match uploaded before the change still reads: every +key is tried in the current layout and then the one it replaced. The tables +below inventory what a match emits, which the change did not alter. Read left to right. The **sources** are the four things running inside one Fargate task. The **filesystem** is laid out the way the container's is. The @@ -55,6 +56,7 @@ flowchart LR classDef sink fill:#1b1420,stroke:#b98ad6,color:#ecdff6 classDef absent fill:#181818,stroke:#6b6b6b,color:#a8a8a8,stroke-dasharray:4 3 classDef svc fill:#101d22,stroke:#4fc1d6,color:#d5eef3 + classDef input fill:#241d10,stroke:#c9a227,color:#f2e6c7 subgraph fargate["one Fargate task — one match, one container"] direction LR @@ -132,11 +134,15 @@ flowchart LR direction TB subgraph bucket["S3 matches/<id>/ — expires at 30 days"] direction TB - kLaunch[("launch/
what it was given")]:::sink - kRaw[("raw/
verbatim MegaMek")]:::sink - kDerived[("derived/
ours")]:::sink - kSocials[("derived/socials/
pictures we picked")]:::sink - kDiag[("diagnostics/
operational")]:::sink + kManifest[("manifest.json · camo-<slot>.png
the inputs — headquarters writes these
before the task starts, and the container
fetches the manifest through a presigned URL")]:::input + subgraph artifacts["artifacts/ — what the container produced"] + direction TB + kLaunch[("launch/
what it was given")]:::sink + kRaw[("raw/
verbatim MegaMek")]:::sink + kDerived[("derived/
ours")]:::sink + kSocials[("derived/socials/
pictures we picked")]:::sink + kDiag[("diagnostics/
operational")]:::sink + end end browser["the player's browser"]:::sink cw[("CloudWatch")]:::sink @@ -266,7 +272,15 @@ about arena's scripts rather than about the data. `shots/` is the worst of them: it holds MegaMek's own board renders and a picture we composed, side by side, with nothing distinguishing the two. -The boundary worth drawing is **provenance**: what the match was handed, what +`matches//` has two writers, and `artifacts/` is what separates them. +Above it are the match's *inputs*, put there by headquarters before the +container exists: the manifest, which is how the container is told what to +play and reaches it as a presigned URL, and each seat's staged camo. Inside it +is everything the container produced. So the first question the layout answers +is not what a file is but whether the match was handed it or made it, and the +prefixes below only have to sort out the second. + +Within `artifacts/`, the boundary worth drawing is **provenance**: what the match was handed, what MegaMek wrote, and what we made out of it. A verbatim MegaMek artifact is evidence — it can be re-read with MegaMek's own tools, and its meaning does not depend on us being correct. Ours is a claim: a rendering, an extraction, a @@ -277,22 +291,29 @@ script ran. ```text matches// - launch/ what the match was given, before it was played - scenario.mms the exact file MegaMek was handed - identity.json slot → DID, handle and team - raw/ verbatim MegaMek, byte-for-byte as it wrote it - game_actions_N.tsv every action and attack, attacker → target - gamelog.html the full round-by-round report - entitystatus.txt record sheets at the end - salvage.mul Bot_*.mul what was destroyed, in MUL - minimap.gif the match, animated - derived/ ours: extracted, rendered or selected by arena - result.json outcome, teams, per-unit state - turns/ the per-phase text reports - socials/ pictures we picked, for people to look at - share-card.png the board at victory, chosen from 31 renders - diagnostics/ operational, nobody's evidence - megamek.log unified_log.log* stats-summary.txt profile-*.collapsed + manifest.json what the match was told to be — written by headquarters, + fetched once by the container through a presigned URL + camo-.png each seat's colours, staged by headquarters + + artifacts/ everything the container produced — arena writes only here, + and the segment is headquarters' (`matches/aws.rs`), not a + name any upload key carries + launch/ what the match was given, before it was played + scenario.mms the exact file MegaMek was handed + identity.json slot → DID, handle and team + raw/ verbatim MegaMek, byte-for-byte as it wrote it + game_actions_N.tsv every action and attack, attacker → target + gamelog.html the full round-by-round report + entitystatus.txt record sheets at the end + salvage.mul Bot_*.mul what was destroyed, in MUL + minimap.gif the match, animated + derived/ ours: extracted, rendered or selected by arena + result.json outcome, teams, per-unit state + turns/ the per-phase text reports + socials/ pictures we picked, for people to look at + share-card.png the board at victory, chosen from 31 renders + diagnostics/ operational, nobody's evidence + megamek.log unified_log.log* stats-summary.txt profile-*.collapsed ``` Four things change from what runs today. -- 2.51.2