@crvouga/atlas 0.16.0 → 1.0.0

package/llms.txt

@@ -21,7 +21,7 @@ Given only the repository link, start at docs/agents.md: install `@crvouga/atlas
 
 - [The report contract](https://raw.githubusercontent.com/crvouga/atlas/main/docs/report-contract.md): This is the normative description of what Atlas reads and writes when it reports on specs of any kind:
 - [Evidence: attachments, timelines, snapshots and everything else](https://raw.githubusercontent.com/crvouga/atlas/main/docs/extending.md): Atlas is opinionated about specs and open about evidence.
-- [Report backends and live snapshots](https://raw.githubusercontent.com/crvouga/atlas/main/docs/report-backends.md): Atlas maps the product's areas, screens, events and journeys from a spec, then overlays evidence of what the product did.
+- [docs/report-backends.md](https://raw.githubusercontent.com/crvouga/atlas/main/docs/report-backends.md): 
 - [Executable statecharts](https://raw.githubusercontent.com/crvouga/atlas/main/docs/statecharts.md): Write down how a product behaves as statecharts in open formats, then let Atlas lint them, plan paths that cover every transition, run those paths against the real product through any driver (a browser, a phone, a pla…
 
 ## Working with this project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.16.0",
+  "version": "1.0.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",
@@ -164,7 +164,7 @@
     "schemas": "bun packages/schema/scripts/emit-json-schemas.ts",
     "docs": "bun scripts/docs/generate.ts",
     "docs:check": "bun test scripts/docs scripts/release/docs-links.test.ts packages/schema/tests/schemas.test.ts packages/server/tests/openapi.test.ts packages/server/tests/settings.test.ts",
-    "dev": "bun packages/core/bin/atlas.mjs dev --data .atlas-data",
+    "dev": "bun packages/core/bin/atlas.mjs dev",
     "client:dev": "bun packages/core/bin/atlas.mjs dev",
     "client:build": "bun packages/core/bin/atlas.mjs client build --no-data",
     "client:publish-data": "bun packages/visualizer/scripts/publish-data.ts",

package/packages/reports/STORAGE.md

@@ -69,7 +69,7 @@ adapter records each part independently.
 
 The existing selected-attempt pointer, reusable content hashes and frame bundles
 continue to own test-run publication. An empty closed run is `skipped`, never a
-successful result inferred from absent evidence. Retention keeps historical evidence and its referenced content, including previous attempts and deleted branches. `pruneReports` reports retained commits and deletes nothing; storage usage grows with unique evidence.
+successful result inferred from absent evidence. Retention keeps historical evidence and its referenced content, including previous attempts and deleted branches. `pruneReports` reports retained commits and deletes nothing; storage usage grows with unique evidence unless an operator saves a garbage collection policy for the server, which deletes only superseded layers (`garbage.ts`, [the server](../../docs/server.md#user-state-and-garbage-collection)).
 
 Large bundles overlap at most four 4 MiB chunk uploads per source. Entry parts
 retain input order even when uploads complete out of order. Backpressure bounds

package/packages/schema/schemas/check-detail.schema.json

@@ -73,6 +73,10 @@
           "type": "number",
           "minimum": 0
         },
+        "recordingExpectation": {
+          "description": "`required`: expect a video of this check, and report whether it was published. `not-applicable`: intentionally unrecorded. Absent: no expectation. Never changes the check's status",
+          "type": "string"
+        },
         "tags": {
           "description": "Free labels to filter and group by: smoke, slow, flaky…",
           "type": "array",
@@ -169,6 +173,10 @@
               "description": {
                 "type": "string"
               },
+              "omitted": {
+                "description": "Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell \"left out\" from \"never recorded\"",
+                "type": "string"
+              },
               "tags": {
                 "description": "Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result",
                 "type": "array",
@@ -404,6 +412,10 @@
                     "description": {
                       "type": "string"
                     },
+                    "omitted": {
+                      "description": "Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell \"left out\" from \"never recorded\"",
+                      "type": "string"
+                    },
                     "tags": {
                       "description": "Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result",
                       "type": "array",
@@ -676,6 +688,10 @@
                           "description": {
                             "type": "string"
                           },
+                          "omitted": {
+                            "description": "Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell \"left out\" from \"never recorded\"",
+                            "type": "string"
+                          },
                           "tags": {
                             "description": "Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result",
                             "type": "array",
@@ -883,6 +899,10 @@
                     "description": {
                       "type": "string"
                     },
+                    "omitted": {
+                      "description": "Why the producer did not include its bytes, in an open vocabulary: too-large, not-found, not-allowed, over-budget, policy… Present on a metadata-only attachment, so a reader can tell \"left out\" from \"never recorded\"",
+                      "type": "string"
+                    },
                     "tags": {
                       "description": "Free labels of this one attachment, such as `demo`: shown as `#demo`, searchable, and normalized by `normalizeTag` (a leading `#` and letter case never matter). Unlike the tags of a check they say nothing about its result",
                       "type": "array",

package/packages/schema/schemas/effective-delta.schema.json

@@ -207,6 +207,22 @@
                     "roles"
                   ],
                   "additionalProperties": {}
+                },
+                "recording": {
+                  "description": "What became of the check's expected recording: uploaded, referenced, skipped, unresolved or not-applicable. Independent of `status`",
+                  "type": "object",
+                  "properties": {
+                    "state": {
+                      "type": "string"
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "state"
+                  ],
+                  "additionalProperties": {}
                 }
               },
               "required": [
@@ -481,6 +497,51 @@
                   "roles"
                 ],
                 "additionalProperties": {}
+              },
+              "recordings": {
+                "description": "How many of the recordings the layer expected were published. Absent: the layer declared no expectations, so its completeness is unknown, not complete",
+                "type": "object",
+                "properties": {
+                  "expected": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "uploaded": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "referenced": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "skipped": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "unresolved": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "notApplicable": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "expected",
+                  "uploaded",
+                  "referenced",
+                  "skipped",
+                  "unresolved",
+                  "notApplicable"
+                ],
+                "additionalProperties": {}
               }
             },
             "required": [

package/packages/schema/schemas/effective-evidence.schema.json

@@ -207,6 +207,22 @@
                     "roles"
                   ],
                   "additionalProperties": {}
+                },
+                "recording": {
+                  "description": "What became of the check's expected recording: uploaded, referenced, skipped, unresolved or not-applicable. Independent of `status`",
+                  "type": "object",
+                  "properties": {
+                    "state": {
+                      "type": "string"
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "state"
+                  ],
+                  "additionalProperties": {}
                 }
               },
               "required": [
@@ -481,6 +497,51 @@
                   "roles"
                 ],
                 "additionalProperties": {}
+              },
+              "recordings": {
+                "description": "How many of the recordings the layer expected were published. Absent: the layer declared no expectations, so its completeness is unknown, not complete",
+                "type": "object",
+                "properties": {
+                  "expected": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "uploaded": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "referenced": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "skipped": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "unresolved": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "notApplicable": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "expected",
+                  "uploaded",
+                  "referenced",
+                  "skipped",
+                  "unresolved",
+                  "notApplicable"
+                ],
+                "additionalProperties": {}
               }
             },
             "required": [

package/packages/schema/schemas/evidence-page.schema.json

@@ -252,6 +252,51 @@
               "roles"
             ],
             "additionalProperties": {}
+          },
+          "recordings": {
+            "description": "How many of the recordings the layer expected were published. Absent: the layer declared no expectations, so its completeness is unknown, not complete",
+            "type": "object",
+            "properties": {
+              "expected": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "uploaded": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "referenced": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "skipped": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "unresolved": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "notApplicable": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "expected",
+              "uploaded",
+              "referenced",
+              "skipped",
+              "unresolved",
+              "notApplicable"
+            ],
+            "additionalProperties": {}
           }
         },
         "required": [

package/packages/schema/schemas/gc-policy.schema.json

@@ -0,0 +1,36 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/gc-policy.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Delete eligible layers on a schedule. `false` keeps the policy but deletes nothing"
+    },
+    "maxAgeDays": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 3650,
+      "description": "A superseded layer is eligible once it was recorded more than this many days ago"
+    },
+    "keepLatest": {
+      "default": 20,
+      "description": "Always keep this many of the newest layers, however old, so recent history stays",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1000000
+    },
+    "intervalHours": {
+      "default": 24,
+      "description": "How often the server applies the policy",
+      "type": "number",
+      "minimum": 1,
+      "maximum": 720
+    }
+  },
+  "required": [
+    "enabled",
+    "maxAgeDays"
+  ],
+  "additionalProperties": false
+}

package/packages/schema/schemas/gc-run-result.schema.json

@@ -0,0 +1,106 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/gc-run-result.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "runs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "project": {
+            "type": "string"
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "at": {
+            "type": "string",
+            "description": "When the pass finished, ISO 8601"
+          },
+          "candidates": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Layers the policy would delete"
+          },
+          "deletedLayers": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "deletedBlobs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "keptLayers": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "error": {
+            "description": "Why the pass stopped early, when it did",
+            "type": "string"
+          }
+        },
+        "required": [
+          "project",
+          "dryRun",
+          "at",
+          "candidates",
+          "deletedLayers",
+          "deletedBlobs",
+          "keptLayers"
+        ],
+        "additionalProperties": {}
+      }
+    },
+    "policy": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Delete eligible layers on a schedule. `false` keeps the policy but deletes nothing"
+            },
+            "maxAgeDays": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3650,
+              "description": "A superseded layer is eligible once it was recorded more than this many days ago"
+            },
+            "keepLatest": {
+              "default": 20,
+              "description": "Always keep this many of the newest layers, however old, so recent history stays",
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1000000
+            },
+            "intervalHours": {
+              "default": 24,
+              "description": "How often the server applies the policy",
+              "type": "number",
+              "minimum": 1,
+              "maximum": 720
+            }
+          },
+          "required": [
+            "enabled",
+            "maxAgeDays"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "runs",
+    "policy"
+  ],
+  "additionalProperties": {}
+}

package/packages/schema/schemas/gc-snapshot.schema.json

@@ -0,0 +1,122 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/gc-snapshot.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "revision": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "policy": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Delete eligible layers on a schedule. `false` keeps the policy but deletes nothing"
+            },
+            "maxAgeDays": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3650,
+              "description": "A superseded layer is eligible once it was recorded more than this many days ago"
+            },
+            "keepLatest": {
+              "default": 20,
+              "description": "Always keep this many of the newest layers, however old, so recent history stays",
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1000000
+            },
+            "intervalHours": {
+              "default": 24,
+              "description": "How often the server applies the policy",
+              "type": "number",
+              "minimum": 1,
+              "maximum": 720
+            }
+          },
+          "required": [
+            "enabled",
+            "maxAgeDays"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "saved": {
+      "type": "boolean",
+      "description": "Whether a policy exists in S3. `false` means garbage collection is off: nothing is deleted"
+    },
+    "lastRuns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "project": {
+            "type": "string"
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "at": {
+            "type": "string",
+            "description": "When the pass finished, ISO 8601"
+          },
+          "candidates": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Layers the policy would delete"
+          },
+          "deletedLayers": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "deletedBlobs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "keptLayers": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "error": {
+            "description": "Why the pass stopped early, when it did",
+            "type": "string"
+          }
+        },
+        "required": [
+          "project",
+          "dryRun",
+          "at",
+          "candidates",
+          "deletedLayers",
+          "deletedBlobs",
+          "keptLayers"
+        ],
+        "additionalProperties": {}
+      },
+      "description": "The most recent pass over each project, newest first; empty before the first pass"
+    },
+    "stateKey": {
+      "type": "string",
+      "description": "Where the user state lives in the bucket, relative to the configured prefix"
+    }
+  },
+  "required": [
+    "revision",
+    "policy",
+    "saved",
+    "lastRuns",
+    "stateKey"
+  ],
+  "additionalProperties": {}
+}

package/packages/schema/schemas/layer-rows.schema.json

@@ -198,6 +198,22 @@
               "roles"
             ],
             "additionalProperties": {}
+          },
+          "recording": {
+            "description": "What became of the check's expected recording: uploaded, referenced, skipped, unresolved or not-applicable. Independent of `status`",
+            "type": "object",
+            "properties": {
+              "state": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "state"
+            ],
+            "additionalProperties": {}
           }
         },
         "required": [