SECS Design — Reading Guide

This is the live entrypoint for the docs/design/ doc set. Read this first, then continue to 00-overview.md for the lowering-contract glossary and doc map.

For first-pass reading, stay on the live docs/design/ path. Historical, audit, recovery, and backlog material remains available elsewhere in docs/, but it is traceability only; the contract path defined here is the authoritative one.

What is SECS

SECS stands for Scripting Engine C Sharp. It is a data-driven scripting engine inspired by Paradox grand strategy games (CK3, EU4, Victoria 3) — specifically by their script systems that let designers and modders define entities, channels, events, and modifiers without touching engine code.

SECS uses a modified C# as its scripting language. .secs files are real C# with extra keywords. The future SECS compiler will transpile .secs to standard C# that the runtime engine consumes. The committed declaration keywords are template, channel, field, modifier, system, event, contract, scope, activity, on_action, policy. The committed mod-operation keywords are inject, replace, try inject, try replace, inject_or_create, replace_or_create. A top-level formula keyword is not committed; formula delegates are generated from dynamic channel sources and dynamic modifier effects. See SECS-Compiler-Plan.md § Source keyword whitelist and grammar status for the source/member/runtime split.

The four sub-projects of this workspace

The secs-workspace repo holds four cooperating pieces:

1. The SECS engine (src/SECS.Abstractions, src/SECS.Engine, src/SECS.Localization) — the runtime library that resolves channels, runs systems, dispatches events, manages modifiers, evaluates policies, executes activities, and accumulates mods. Targets netstandard2.1 so it can ship inside Unity.

2. The Valenar example game (examples/valenar/) — a colony-builder that exercises every engine feature end-to-end. Doubles as integration test, demo, and the specification for what the future SECS compiler must emit. Has its own dev server (ASP.NET Core SignalR + React client).

3. The forked C# compiler (secs-roslyn/ git submodule) — a fork of dotnet/roslyn that will be extended with SECS keywords. Compiler work is currently deferred, so the Generated/ pattern remains the live executable stand-in until that work resumes.

4. The language specification (docs/) — docs/design/ is the live SECS contract path (this directory). docs/decisions/ records ADRs and docs/research/ holds non-authoritative exploration notes.

Legend

• Current contract — this README plus 00-overview.md through 10-host-secs-execution-boundary.md.
• Current executable stand-in — examples/valenar/Generated/*.cs. Hand-written stand-ins the runtime consumes today.
• Intended source surface — examples/valenar/Content/*.secs. Designer-facing source shape for the future compiler.
• Compiler implementation backlog — SECS-Compiler-Plan.md. Planning only, not first-pass contract reading.
• History / audit / recovery — docs/RECOVERY_*.md, docs/WAVE_REFACTOR_AUDIT.md, docs/design/audit-findings.md, docs/design/mod-coverage-audit.md. Traceability only; they do not override the live contract path.
• Backlog / proposals — docs/design/FUTURE_WORK.md and docs/research/. Planning only.

Content / Generated / future compiler

Three surfaces cooperate:

• examples/valenar/Content/*.secs — intended source surface for designers.
• examples/valenar/Generated/*.cs — current executable stand-in for compiler output.
• The future SECS compiler — the bridge that will lower Content/ into the Generated/ shape.

The live contract is the pairing between the numbered design docs and the current Generated/ patterns. When a numbered design doc explicitly replaces an older stand-in, the design doc wins.

Live reading path

1. Read this file for the doc-set legend and route.
2. Read 00-overview.md for glossary, doc map, and diagnostic routing.
3. Read the numbered docs in order when you need the full lowering contract.
4. Use the relevant numbered doc's local glossary, notes, and cross-references when you need deeper semantic detail.
5. Use recovery, audit, and backlog docs only for provenance or future planning.

The seven core SECS concepts

These are the declaration kinds that shape the SECS programming model. Lifted verbatim from .claude/rules/secs-concepts.md:

Concept	What it is	Lifecycle
Template	Defines what entities ARE. Static. Registers intrinsic channel sources, implements contract queries and methods.	Registered at startup; looked up by the FNV-1a-64 hash of its canonical id string (for example, valenar:template/building/farm).
System	Defines what HAPPENS each tick. Non-static. Frequency-gated, phased.	Runs in pipeline order during TickContext.Tick().
Event	Defines what happens WHEN. Pulse-triggered, on_action-triggered, or player-choice-triggered.	EventDispatcher evaluates triggers per-tick.
Modifier	Reusable effect bundle (stacking + triggers + duration + decay).	Attached by host or by OnAction; managed by ModifierBindingStore.
Formula	Dynamic value used by intrinsic channel sources or modifier effects at resolution time.	Evaluated lazily during channel resolution; cached in ChannelCache.
Scope	Host-defined hierarchy node (Empire, County, Building). Walked via WalkScope.	Static hierarchy maintained by host.
Mod operation / slot merge	Layered content changes expressed with inject, replace, try inject, try replace, inject_or_create, or replace_or_create. Operations target compiler-owned semantic slots; later load-order writes win for the same slot.	Resolved by the compiler pre-binding merge pass, with the shipped activity/policy runtime finalizer as the current executable subset.

Full prose definitions live in 00-overview.md § Glossary.

The behavior layer

The current behavior surface adds four live concepts on top of the seven core definitions:

• Activity — executable behavior units the runtime can start, preview, and track. See 04-behavior.md § Activities.
• Policy — chooser logic built from needs, selectors, and rules that selects among activities. See 09-ai-policies-and-activities.md.
• Slot — per-actor mutable lists and related runtime-authored behavior data. See 04-behavior.md § Slots.
• Mod — layered declaration changes that target the slot schema and merge pipeline. See 06-overrides-and-modding.md.

Warn-only registry diagnostics are also part of the live contract and are documented alongside the relevant features.

Compiler status

Compiler work remains deferred. The current contract lives in the numbered design docs and in the hand-written stand-ins under examples/valenar/Generated/. SECS-Compiler-Plan.md is the implementation backlog for when compiler work resumes, not part of the first-pass reading path.

Doc tour

Use this table as the live contract map. Numbered docs are the first-pass path; history, audit, and backlog docs are secondary destinations.

Doc	Covers
00-overview	Lowering-contract entry point. Glossary. Feature-block template. Master diagnostic table (SECS0xxx codes). Diagnostic channels. Read after this README.
01-world-shape	World/scope schema. scope, walks_to, ScopedList<T>, ScopedDictionary<TKey,T>. How the host's hierarchy gets declared.
02-templates	The template keyword. Channel sources, contract methods, lifecycle bindings. The most foundational doc.
03-channels-and-modifiers	The 6-phase channel resolution pipeline (base → additive → multiplicative → HardOverride → clamp → return). Modifier declarations, propagation, stacking, decay. track_prev snapshots. SECS0303 formula read-set warning.
04-behavior	Systems, events, on-actions, activities, policies, slots, and static analysis. The "what happens" layer.
05-expressions	Expression model. Lambda bodies, captured locals, @this / owner references.
06-overrides-and-modding	The modding contract. Six mod operations. Slot schema (§8.1–§8.11). Severity model (§12.1). Registry static analysis (§12.2).
07-structured-template-data-and-callables	SecsTypeRef, structured template data, typed callable signatures. Replaces the older SecsValueKind design.
08-collections-and-propagation	Collection iteration, aggregate accessors (Children.Sum, .Where), modifier propagation, previous-tick bridge reads, registry_only design intent and current gap.
09-ai-policies-and-activities	Policies, utility-AI scoring, activities, runtime player slots, mod injection examples. The behavior-layer narrative.
10-host-secs-execution-boundary	Ownership classification, assembly placement, host bridge contract, invocation rules, and the current partial save/load boundary.

Secondary destinations:

Doc	Role
audit-findings	Spec audit findings collected during refactors. Historical traceability only.
mod-coverage-audit	Coverage audit of mod operations against spec. Historical traceability only.
FUTURE_WORK	Deferred engine work, compiler backlog, and doc-cleanup punch list. Backlog, not current contract.

Doc-set roles (where things live)

Location	Role
docs/design/ (this directory)	Authoritative lowering contract. What the compiler must emit. SECS source + lowered C# pairs.
Historical audits / recovery docs elsewhere under docs/	Provenance and cleanup history. Useful for traceability, but not part of the live contract path.
docs/decisions/	Architectural decision records (ADRs). Why the Roslyn fork, why netstandard2.1, etc.
docs/research/	Exploration notes. Not authoritative. Treat decisions as authoritative, research as scratch.
CLAUDE.md (workspace root)	Workspace identity, tenets, universal commands. Read alongside this README.
.claude/rules/*.md	Path-scoped rules that auto-load when working in specific subsystems (netstandard2.1 polyfills, mapgen invariants, SECS concepts, etc.).
SECS-Compiler-Plan.md (workspace root)	Eight-phase plan for building the SECS compiler on the Roslyn fork. Currently deferred.

Reading order

• Fresh orientation — CLAUDE.md, this README, 00-overview.md, then the numbered docs you need.
• Full contract read — 00-overview.md through 10-host-secs-execution-boundary.md in order.
• Semantics questions — stay on the numbered design docs and follow their local cross-references; the live contract path carries the current semantics.
• Planning work — use FUTURE_WORK.md and SECS-Compiler-Plan.md only after the live path.

Status snapshot (May 2026)

• The runtime engine ships and is benchmarked.
• The live behavior surface includes activities, policies, runtime slots, the mod runtime, and registry diagnostics.
• The SECS compiler does not exist yet, and compiler implementation is currently deferred.
• examples/valenar/Generated/ remains the executable lowering reference until compiler work resumes.