LOCAL RAID COLLECTOR - READ-ONLY OBSERVATIONS

Run Start Raid Collector.cmd when you want collection; Stop Raid Collector.cmd
requests a stop within ten seconds. No scheduled task, startup entry, network
connection, Discord post, DKP update or website upload is installed or performed.
The launcher has not been run against the live log as part of development.

Defaults: D:\EQ and D:\EQ\Logs\eqlog_Zaknaffein_cazic.txt. To change paths,
run Watch-RaidSources.ps1 with -GameRoot, -LogPath and -StateRoot. Windows
PowerShell 5.1 is supported. Use -Once for a single bounded pass. The first pass
starts at the current log EOF. -FromBeginning explicitly replays a disposable
or historical log only when its state folder has no existing log checkpoint.
The local Windows time zone is persisted; use -TimeZoneId 'Central Standard Time'
to specify it. Ambiguous or nonexistent daylight-saving timestamps are held.

The collector reads at most 1 MiB of appended log bytes per pass. It saves a
Windows file identity, byte offset and checkpoint hash; replacement/truncation
starts the new source at byte zero. An in-place rewrite that has already regrown
past the checkpoint rebaselines at EOF to avoid replaying historical text. All
source resets become structured observations. Partial lines wait for a newline;
oversized lines are skipped. Original EQ files are never modified.

Only the exact observed system message '--Character has looted a Item.--' is
recognized. Each result retains the item, character, time, source position and
line hash. Ordinary chat, tells, bids, awards and unverified announcement formats
are ignored. No raw log lines or conversations are copied to output. Loot is
an observation: raid/encounter, owner, price and DKP remain unresolved. Bidding
needs an actual validated guild announcement format before it can be enabled.

RaidRoster_<server>-YYYYMMDD-HHMMSS.txt files in D:\EQ are read after a stable
three-second interval and an exclusive-open check. Actual October 5 samples have
nine tab-separated fields: group, character, level, class, then five flags.
Only the first four fields are consumed. Unsupported rows/duplicates hold the
whole snapshot for correction. Existing dumps retain their filename source time
in timestamp; observedAt separately records when the collector read them.
outOfOrder means a source time predates the latest recorded snapshot; it does
not measure snapshot age. The roster change window is bounded by two
snapshots; arrival/departure/group-change times are not inferred more precisely.
Groups 11 and 12 are flagged coin-only; group 10 is not excluded by group number.
Owner/role remain unresolved, and no
attendance credit, AFK decision, earnings or points calculation is performed.
Generate fresh in-game Raid Dumps at start, checkpoints and roster/group changes;
the watcher cannot create an in-game dump.

The default private state folder is work\raid-collector\runtime beside the
eq-calendar project, outside its public repository. records.jsonl contains
structured observations and roster snapshots. state.json is an atomic checkpoint
with a previous-state backup. These contain private character/item
data and should stay local. Retrying a persisted observation does not duplicate
its record, including a restart after journal append but before state update.
A damaged journal stops collection rather than silently replaying data; preserve
the state folder for diagnosis. Changed old snapshots are retained as out-of-order
observations and do not alter later roster change windows.

The existing scripts\parse-uploader separately publishes deliberately exported,
reviewed EQLogParser CSV summaries to the public /parses archive. This collector
does not calculate automatic parses or send its private roster/loot records to
that public endpoint. Exact bidding, identity and guild-policy verification,
encounter binding and a private ingest API remain later integration work.

Run Test-RaidCollector.ps1 for disposable synthetic validation. It does not start
the watcher or read the live combat log. Real roster schema validation can be
run separately with Validate-RaidDumpSamples.ps1; only aggregate results print.
