BOR-517: define the v1 event model and sample fixtures

[bdclaw2026]

Summary

• add a small Go event package that defines and validates the v1 normalized event shape
• document required vs optional event fields and link the schema doc from the README
• add JSON, logfmt, key=value, and plain text fixtures with coverage in tests

Validation

• mise exec go@1.25.7 -- go test ./pkg/...
• mise exec go@1.25.7 -- go test ./integration_test/...
• mise exec go@1.25.7 -- golangci-lint run

Refs BOR-517

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational v1 normalized event model for log processing within the lapp system. It introduces a Go package to formally define this event structure, accompanied by detailed documentation outlining its fields and their purpose. To ensure consistency and facilitate future development, a suite of diverse log format fixtures has been added, complete with validation logic, providing concrete examples of how various log types map to the new event schema.

Highlights

• Event Model Definition: A new Go package pkg/event was introduced to define the v1 normalized event shape, including Event, Inferred, and Fixture structs.
• Schema Documentation: Comprehensive documentation for the v1 event schema was added in docs/event-schema-v1.md, detailing required/optional fields and the canonical structure.
• Sample Fixtures: A set of sample event fixtures covering JSON, logfmt, key=value, and plain text formats were added under fixtures/events/v1/ to aid in testing and validation.
• Fixture Validation & Loading: The pkg/event package includes logic to validate the structure of these fixtures and a utility function LoadFixtures to read them from disk.

Changelog

• README.md
  • Added a new section "Event Schema" with a link to the v1 event schema documentation and a mention of the new fixture files.
• docs/event-schema-v1.md
  • Created a new markdown document detailing the v1 event schema.
  • Defined the canonical JSON shape for events.
  • Documented top-level fields (ts, text, attrs, inferred) with types, required status, and notes.
  • Specified recommended canonical keys for attrs (e.g., level, service, request_id).
  • Described inferred metadata fields (pattern, entity).
  • Listed the new fixture files that provide coverage for the schema.
• fixtures/events/v1/json-checkout-failure.json
  • Added a JSON fixture representing a checkout failure event.
• fixtures/events/v1/key-value-retry.json
  • Added a key-value fixture representing a retry event.
• fixtures/events/v1/logfmt-auth-success.json
  • Added a logfmt fixture representing an authentication success event.
• fixtures/events/v1/plain-text-worker-stall.json
  • Added a plain text fixture representing a worker stall event.
• pkg/event/v1.go
  • Created a new Go file defining the event package.
  • Defined constants for SourceFormatJSON, SourceFormatLogfmt, SourceFormatKeyValue, SourceFormatPlainText.
  • Declared allowedSourceFormats map for validation.
  • Defined the Event struct for the v1 normalized log event shape, including Timestamp, Text, Attrs, and Inferred.
  • Defined the Inferred struct for metadata derived after parsing, including Pattern and Entity.
  • Defined the Fixture struct to wrap an example event with provenance metadata.
  • Implemented the Validate() method for Fixture to ensure it conforms to the v1 contract.
  • Implemented the LoadFixtures() function to read and validate JSON fixture files from a directory.
• pkg/event/v1_test.go
  • Created a new Go test file for the event package.
  • Added TestLoadFixtures to verify that all expected fixture types are loaded correctly and that the LoadFixtures function works as intended.

Activity

• The pull request author, bdclaw2026, created this pull request to define the v1 event model and add sample fixtures.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a v1 event model for normalized log events, including the Go data structures, validation logic, and test fixtures. The changes are well-structured, with clear documentation for the new event schema. My review includes suggestions to improve maintainability in the validation logic, enhance the robustness of the tests by removing magic numbers, and a minor clarification in the documentation.