feat(classic): emit audit events for scripted quest and economy transactions

[zoeyrose]

Architecture amendment — one authored content source (2026-08-13)

Initiative atrinik/atrinik#357 supersedes every future live-branch instruction below. atrinik/content@main is the sole mutable authored source for replacement and Classic targets. Future authored changes land only on main; supported Classic artifacts are deterministically derived from the same immutable main revision. Do not create, restore, author, backport, validate, or publish through a live 1.x branch.

Exact historical 1.x commits, tags, releases, assets, preserved local snapshots, provenance, parity records, and comparisons remain valid immutable evidence. This amendment changes no other feature, balance, lore, compatibility, licensing, validation, or ownership acceptance criterion.

Context

Classic C code cannot observe the complete semantic outcome of transactions implemented by trusted content scripts. This issue covers the authored 1.x integration after these server contracts exist:

• classic#159: durable private journal and trusted-Python API;
• classic#161: quest/progression milestone taxonomy;
• classic#162: item/currency transaction records.

Do not make scripts append raw log text. They should call a narrow typed API with stable event/reason identifiers and transaction context; the server remains responsible for schema, privacy, durability, and storage.

Prime content-owned paths

The survey identified these centralized 1.x paths, rather than every individual map, as the first integration points:

• quest and nested-part lifecycle in QuestManager.py, including objective-item removal/retention and repeat handling;
• persistent post serialization/delivery in PostOffice.py and payment/send/destruction in postoffice_clerk.py;
• auction purchase/payout/delivery in Auction.py and listing/withdrawal in auctions/clerk.py;
• scripted item/spell purchase and item sale in Merchant.py;
• low-volume existing metric sites for housing/apartment purchase and fees, bounty payment/clear, guild join/leave/storage, and jail placement;
• privileged quest reset and XP adjustment commands.

Several post, auction, and merchant flows currently perform payment, serialization, insertion/destruction, payout, and metric updates as separate steps. A record written only after the last step cannot recover a crash in the middle.

Required integration

• Emit centralized quest start/part-start/complete/fail/repeat/reset, objective-item acquisition/removal, and kill-threshold events with the stable identifiers defined by feat(maps): transfer crystal light ownership #161. Do not add bespoke raw logging to each quest.
• Wrap each post, auction, merchant, housing, and similar logical exchange in one transaction identity using the intent/commit/reconciliation contract from fix(release-lines): synchronize classic descriptor #159.
• Include actor, counterparty/service, item lineage and quantity, amount, carried/bank funding when known, and typed reason; correlate payout and delivery sides.
• Make multi-step operations idempotent so reconciliation cannot duplicate money/items or lose a successfully paid-for delivery.
• Audit the remaining scripted metric sites and classify each as gameplay journal, aggregate-only, operational/security log, or not recorded. Add events only where volume and recovery/support value justify them.
• Replace or supplement pre-operation/human-text audit-like facilities such as guild storage logging with authoritative successful transaction events. Do not retain arbitrary player text in structured records.

Branch scope

The runtime target is 1.x, because this integration depends on the Classic trusted-Python API. In the implementation PR, explicitly record the branch disposition: forward-port framework-neutral changes to main when compatible, and keep Classic-only calls off main when they are not. Validate both branches when shared files are changed.

Acceptance criteria

• Central QuestManager tests prove top-level/nested/repeat/reset and objective events are emitted once with stable IDs and no per-state-write noise.
• Post send/receive, auction list/withdraw/buy/payout, merchant buy/sell, and selected service payments have one correlated logical transaction each.
• Forced failure/crash tests at every multi-step boundary reconcile without item/currency loss or duplication.
• Failed payment, rejected delivery, insufficient capacity, and script exceptions never appear as committed successes.
• Existing metrics remain correct and are not double-counted through both generic payment and business-specific hooks.
• Every existing scripted metric site is classified; high-volume or low-value exclusions are documented.
• Structured events contain no secrets, chat, arbitrary inscription/item text, or raw script-supplied JSON/log lines.
• 1.x validation passes, and the PR states what was or was not mirrored to main and why.

Non-goals

• Implementing a separate content-owned audit file or recovery tool.
• Adding one-off logging to every quest/map when the framework already owns the transition.

[zoeyrose]

Draft prerequisite work is published in #222 at 7f7e8eab602337cff386f2102c6a472a24ec3c55. It inventories and classifies the current scripted telemetry surface; all local validation and hosted checks pass, and the PR remains intentionally draft/non-closing. Executable delivery is blocked on the still-open typed quest contract atrinik/classic#161 and correlated/idempotent economy transaction contract atrinik/classic#313. No Classic PR currently implements either gate, so the quest/economy producers and required crash/replay scenarios cannot yet be implemented against a stable server API without violating this issue’s server-owned journal boundary.

[zoeyrose]

Update: Classic #161 is now closed by atrinik/classic#319, and the corresponding centralized content integration landed in #223. Draft #222 has been merged forward to current content main and its inventory is aligned with those quest producers at af8c3b2dcb32f02d294aa4a21497b0c825cdc01d; local aggregate validation passes. Classic #313 remains OPEN with no implementation PR, so correlated/idempotent post, auction, merchant, housing, and service transactions plus crash/replay scenarios remain the sole executable blocker.

[zoeyrose]

Continuation update at content@42c73945a2d35c6823000790c18374505914bb84:

• feat(server): audit meaningful quest, progression, and survival milestones classic#161 is closed and its typed quest/progression contract is integrated through feat(quests): journal lifecycle milestones #223.
• The content branch now preserves retryable quest-part state across objective-cleanup exceptions and can resume the whole-quest transition after the part transition has committed.
• Failure review identified a remaining server contract gap: trusted Python cannot supply/recover a stable quest operation key or query/idempotently repeat an uncertain commit. That recovery work is now tracked separately by feat(server): reconcile scripted quest transitions classic#321.
• The multi-step economy correlation/reconciliation contract at feat(server): correlate scripted economy transactions classic#313 remains open.

PR #222 remains draft and non-closing while #321 and #313 gate the restart/replay and economy acceptance criteria. The current content aggregate validation passes (218 tests plus all repository gates); latest-head Classic runtime verification will be rerun after the dependent server contracts are available.

[zoeyrose]

Post-review correction at content@a0e14034d6a8f64650e7cea34c6f44c1ec68bba8:

The attempted content-local quest replay ordering from the prior update was removed before merge readiness. Independent failure injection proved that retrying after a partial multi-stack objective cleanup could over-remove items, and terminal-part resume could choose the wrong whole-quest outcome for mixed terminal siblings. Those operations require the server-owned stable identity/disposition boundary rather than a content heuristic.

atrinik/classic#321 now explicitly includes atomic/idempotent objective cleanup and exactly-once quest aggregate projection. The content branch retains the safe typed lifecycle integration and adds local reason/failure coverage without claiming crash-safe replay. The audit inventory was also extended to 19 sites, including the interactive operator-console execution boundary, with 55 focused scanner tests and 222 aggregate tests passing locally.

PR #222 remains draft and non-closing while atrinik/classic#321 and atrinik/classic#313 remain open.