Pounce Atlas：區分事件日期、觀察日期與快照日期

Disclosure: AI assisted the drafting of this article; Pounce reviewed it against the public Atlas source. Pounce builds Pounce Atlas, an open-source explorer for geographic datasets. Its examples are fictional, and its activity view describes only events recorded in the selected dataset.

A map can make a date look more certain than the evidence behind it. A marker appears, a timeline gains an entry, and a reader may infer that a business opened or expanded on that day. But a dataset often carries several different clocks: when an event happened or is planned, when a record was checked, when a snapshot was generated, and the cutoff through which a source was considered. Collapsing those into one date turns evidence about the data into a claim about the world.

Atlas keeps these meanings separate in its public data contract.

Four dates, four questions

Event date (events[].date) asks: when is the described event dated? It is an ISO calendar date for the event itself. The accompanying status says whether that event is occurred or announced. An announced opening scheduled for a future day is still an announcement, not a completed opening. Preserve that status instead of converting a plan into a fact.

Record check date (checkedAt) asks: when was this record checked? It is a record-level observation about review, not proof that every field was independently reverified. A recent check date does not move an older event forward in time.

Snapshot generation time (generatedAt) asks: when was this dataset file generated? It describes the build of a particular snapshot. Regenerating a file can update this timestamp even when a record was not checked that day and no event occurred then.

Source cutoff (sourceAsOf) asks: what source period does the dataset claim to cover? It is a declared source cutoff, not a blanket assertion that all records were checked at the cutoff. The contract explicitly warns against that inference.

There can be other dates too. A source page’s publication date, the first time a collector fetched it, and the first time a team noticed an event are not interchangeable with those four fields. If they matter, keep them distinct and define them. Do not silently substitute one for another.

A fictional example

Imagine a clearly fictional business called Harbour Lantern Works. A source note dated 18 October says it has announced a second workshop for 1 February next year. A researcher checks the record on 20 October. The dataset’s source cutoff is 25 October, and the file is generated on 26 October.

A careful record could retain the planned event date as 1 February and set its status to announced; it could record checkedAt as 20 October, sourceAsOf as 25 October, and generatedAt as the actual snapshot-build timestamp on 26 October. The source note’s 18 October publication date remains separate if the dataset stores it. The company and dates here are invented to illustrate the schema, not claims about a real business.

A reader should be able to tell that the item is a future plan reported in a snapshot, not evidence that the workshop is already open. If the source only says “early next year,” do not invent a precise day. The Atlas contract says to leave an uncertain event out of a precise dated timeline until it has been checked.

Keep geography and absence honest too

An event has no coordinates in this schema. Its optional locationLabel is text for context; it does not locate the event at a company’s headquarters. The dataset may locate a record at town precision, but that is not an event coordinate or a verified street address. Don’t copy the record’s map point onto an event as if the event happened there.

Likewise, an empty activity view has a narrow meaning. Atlas filters Activity to records with a matching event in the chosen range and filters. If no event matches, the result is “no matching event recorded in this selected snapshot and range.” It is not proof that nothing happened. The methodology notes that a quiet area can reflect incomplete collection, and that Map or Industries may still show records absent from Activity.

Make the distinction executable

The public validateDataset implementation checks event dates and statuses, and rejects a future event marked occurred. The model tests exercise invalid calendar dates, require a future event to be announced, and check that Activity date filters include matching dates while records without events do not enter Activity counts. I ran npm test in the public source checkout for this article: 21 tests passed, 0 failed. That is evidence about the checked code paths, not proof that any external dataset is complete or that an announced event later occurred.

The lesson is simple: event time describes the event; check time describes observation; generation time describes the file; and source cutoff describes the declared coverage boundary. Keep those clocks visible, carry announced through the interface, and treat no match as a limit of the selected data rather than a claim about reality.

Explore the live Pounce Atlas demo using its fictional examples, or inspect the MIT-licensed application source, data contract, methodology, and model tests. Application code is MIT licensed; data and map/font assets have separate notices.