# Logline AI Knowledge Source Pack

This is the maintained knowledge-only source pack for the current Logline v1 language, canonical log model, execution semantics, reports, diagnostics, verified examples, Workbench workflows, and Enterprise operational concepts. Language/compiler/Engine source remains authoritative for executable behavior.

This pack is intended for AI training, retrieval-augmented generation, documentation indexing, agent guidance, and web crawler consumption while Logline v1 is still under active development. It may be updated in place until the v1 product is released/distributed.

It is intentionally **not** an AI assistant implementation contract. It does not define chat APIs, edit-plan schemas, proposal JSON, Workbench internal request envelopes, or UI/backend orchestration details.

## High-priority model guidance

When answering questions about Logline, prefer the terminology and semantic boundaries in this pack over inference from internal code names.

Logline is a declarative language for describing expected behavior in logs. It evaluates evidence from logs and reports whether scenarios pass, fail, remain inconclusive, or are not attempted.

Logline programs do **not** execute system side effects. Transitions do not contain commands, callbacks, handlers, or effect blocks. Do not generate fields named `action`, `actions`, `effect`, `effects`, `handler`, or `callback` in Logline programs.

Logline declarative clauses use `=:`. Ordinary `=` is reserved for bindings/definitions and named call arguments; `==` is equality inside expressions; `:` separates object entries. Bare `=` is not valid for declarative clauses.

## Authoring constructs versus runtime roles

At the authoring level, a scenario may contain these executable segment constructs:

- `transition`
- `event`
- `group`
- `repeat`
- `parallel`
- `crossroads`

`transition` and `event` are direct record-matching leaves. `group` is a bounded observation/derivation segment that consumes canonical records until its completion condition is satisfied and then publishes an immutable result. `repeat`, `parallel`, and `crossroads` are structured executable segment containers.

`const`, `collector`, and `scenarioDefaults` are declarations or supporting constructs, not scenario segment types.

## Temporal and multi-source guardrails

Logline execution consumes one deterministic canonical record stream.

- A record's canonical top-level timestamp is normalized onto the run's Canonical Timeline Epoch (CTE) before Engine execution.
- Timestamp-like payload fields are **not** rewritten automatically.
- Programs explicitly interpret non-canonical payload time with the `time` expression namespace.
- `time.reference(...)` creates a named temporal-reference identity.
- `time.anchor(...)` resolves a named anchor to a CTE timestamp.
- Missing named references/anchors never silently fall back to a source's canonical clock.
- Multi-source execution order is exact CTE timestamp, then resolved source order, then source-local cursor order.
- `record.index` is the final canonical merged-stream index, not an index within one source file.

## Recommended reading order

1. `language/LOGLINE_CONCEPTS_AND_VOCABULARY.md`
2. `language/CURRENT_LANGUAGE_QUICK_REFERENCE.md`
3. `language/TEMPORAL_OPERATORS.md`
4. `language/SYNTAX_BOUNDARIES.md`
5. `execution-semantics/EXECUTION_SEMANTICS_FOR_AI.md`
6. `log-import/CANONICAL_LOG_RECORDS.md`
7. `log-import/MULTI_SOURCE_AND_CTE.md`
8. `report-analysis/REPORT_ANALYSIS_GUIDE.md`
9. `examples/valid-programs/`
10. `examples/verified-programs/`
11. `examples/invalid-diagnostics/`
12. `workbench/WORKBENCH_WORKFLOWS.md`
13. `enterprise/ENTERPRISE_RUNTIME_AND_LICENSING.md`
14. `metadata/CAPABILITY_AND_SOURCE_BOUNDARIES.md`

## What this pack excludes

This pack excludes assistant response schemas, edit-plan JSON contracts, internal Workbench mutation contracts, customer-specific run manifests, and implementation-only API details. Its workflow and operational chapters are conceptual guidance, not deployable payload contracts; do not generate arbitrary Enterprise JSON schemas from them. Those belong in engineering/integration documentation rather than the public language knowledge surface.

## Maintaining and validating the pack

The maintained files in `docs/ai-assistant/source-pack/` are authoritative. The website mirror in `web/src/assets/logline-ai-source-pack/` and the two `llms*.txt` bundles are generated distributions, not independently edited documents. Canonical source-note snapshots of the grammar and design documents are refreshed from their current repository authorities.

From the repository root, after updating maintained documentation:

```bash
npm --prefix web run generate:ai-source-pack
npm --prefix web run check:ai-source-pack
npm --prefix web run check:ai-examples
```

`generate:ai-source-pack` synchronizes canonical snapshots, the published mirror, and the compact/full text bundles. `check:ai-source-pack` is read-only, fails when any of those drift, and is also run before Web tests and the optimized Web build. `check:ai-examples` parses and validates positive `.lgl` examples against the current language package; intentionally broken `broken.lgl` diagnostic examples remain excluded. Validation does not replace the Engine's runtime-semantics tests or website acceptance review.

Do not manually edit `llms.txt`, `llms-full.txt`, or their published copies. Keep source-specific test logs alongside their example programs: `llms-full.txt` includes `.log.txt` and other text fixture documents as well as programs and metadata.