Scope and Semantics Review Packet

Purpose

This review packet exists because the user asked for one place to review the missing or incomplete live scope documentation and the adjacent semantic gaps surfaced by two completed audits:

• live-docs/guidance scope-gap audit
• runtime/tests/generated scope-semantics audit

This file is not the current normative contract. The normative sources remain the live design docs such as 00-overview.md, 01-world-shape.md, 03-channels-and-modifiers.md, 04-behavior.md, 05-expressions.md, 07-structured-template-data-and-callables.md, 08-collections-and-propagation.md, 09-ai-policies-and-activities.md, 10-host-secs-execution-boundary.md, and FUTURE_WORK.md.

Executive Summary

• The live docs are structurally present and already cover much of the lowering contract, but they are still narratively thin in the exact places a reviewer needs when trying to understand scope behavior end to end.
• Archive deletion did not remove the authoritative current semantics. The live contract is still in the numbered design docs. What the deletion exposed was that the live docs often distribute scope rules across several files without a synthesis pass.
• The problem is not only “missing scope docs.” The audits also surfaced adjacent live semantic and documentation gaps around captures, runtime enforcement, collection contracts, registry-only behavior, upgrade syntax, typed activity args syntax, and diagnostics mapping.
• The runtime/tests/generated audit showed that many semantics are in fact implemented or at least concretely shaped in code/tests/generated output: ScopeDeclaration, ScopeFrame, WalkScope, collection iteration, scope slots/saved scopes, contract query/method dispatch, and query-keyword lowering all have meaningful live evidence.
• The highest-risk review area is where runtime shape and live narrative are still misaligned or incomplete: captured0/captured1, TemplateActivator scope-root resolution, collection hook host responsibility, WalkScope self-walk/multi-hop rules, provided-scope enforcement, and untested query forms.

Existing Live Coverage Map

The live docs already cover substantial ground; the issue is synthesis and completeness, not total absence.

Live doc	What it currently covers	What is still weak for review purposes
00-overview.md	Declares the doc set as a lowering-contract reference, not a tutorial; glossary includes scope, scope frame, modifier binding, registry_only, collections, on-actions, activity args.	Glossary-level statements are useful but not enough to replace narrative synthesis.
01-world-shape.md	Scope declarations, walks_to, scope fields, contracts, scope methods, typed collections summary, structural compile-time graph.	Walk semantics are defined in pieces, but reviewer-friendly end-to-end scope behavior is still scattered.
02-templates.md	Template root-scope model, intrinsic channels, lifecycle bindings, template-side callable surface.	Scope-frame differences between creation-time and existing-instance call sites are not synthesized here.
03-channels-and-modifiers.md	Trigger lowering, formula lowering, modifier bindings, captured0/captured1 intent, dynamic effect model.	Root/prev capture is described as intended shape, but runtime/compiler implementation is still incomplete.
04-behavior.md	Systems, events, on-actions, activities, scheduler shape, firing model, behavior declarations.	On-action declaration semantics, saved-scope examples, upgrade syntax, and some source-shape examples remain thin.
05-expressions.md	Built-in sigils, scope frames, field reads, channel resolves, add_modifier, remove_modifier, foreach, collection iteration, query-keyword lowerings, command flush semantics.	This is the main live scope doc, but several key scope rules are spread across examples and not synthesized enough for nested/edge cases.
06-overrides-and-modding.md	Merge slots, mod-operation vocabulary, closed/open surfaces.	Diagnostic-map and some source-surface references remain incomplete relative to later docs.
07-structured-template-data-and-callables.md	Typed returns, SecsTypeRef, structured fields, typed callables, scope query/command metadata.	Scope-method source examples and lowering walkthroughs are still not complete enough for review.
08-collections-and-propagation.md	ScopedList<T>, ScopedDictionary<TKey,T>, anonymous collection scopes, aggregate accessors, propagation, registry[id], collection hooks, prev-tick, system slots.	Collection host/runtime responsibilities, query semantics, weak spots around hook ownership, and registry_only enforcement remain underspecified.
09-ai-policies-and-activities.md	Policy/activity semantics, AI flow, needs/selectors/rules.	Typed activity args are explained more by runtime shape than by complete author-facing source syntax.
10-host-secs-execution-boundary.md	Ownership split between host and SECS; bridge responsibilities; state/code ownership.	Good boundary map, but not a substitute for concrete scope semantic examples.
FUTURE_WORK.md	Explicit backlog for unresolved engine/compiler/doc gaps, including captured0/captured1, registry_only, DestroyEntityWithChildren, ResourceProductionSystem frequency, and the root/prev capture note in §5.7.	It records open work, but it is not a narrative review packet and does not replace live contract prose.

Missing or Weak Scope Topics

1. Root/prev capture semantics for nested foreach trigger bindings

• This is the clearest missing synthesis gap.
• 05-expressions.md and 03-channels-and-modifiers.md describe the intended capture slots, but the practical “which enclosing scope goes into which slot at which nesting depth” rule is still weak.
• FUTURE_WORK.md §5.7 explicitly says archive docs previously described the goal and that the rule still needs to be spelled out before implementation.
• This should be treated as both a documentation gap and a semantic-risk gap.

2. Saved-scope / dispatch-frame lifecycle examples

• The runtime audit found meaningful live behavior around saved scopes and event dispatch frames.
• The live docs mention save_scope_as, saved scopes, and scope frames, but there is no compact walkthrough of save → fire → retrieve → auto-clear behavior across an event sequence.
• Reviewers currently have to reconstruct this from 04-behavior.md, 05-expressions.md, runtime code, and generated event examples.

3. Null-walk runtime defensive patterns

• Live docs now reject undeclared walks and document declared walks_to edges, but defensive runtime behavior still appears in examples and edge-path discussion.
• The missing piece is a reviewer-facing statement of when null is expected, when null is an error, and when a null walk must make a trigger/query false instead of silently degrading.
• This is especially important for trigger captures and cross-scope reads.

4. Creation-time vs existing-instance scope-frame behavior across call sites

• The docs describe @root, @this, @prev, and @owner, but the call-site matrix remains hard to see at a glance.
• Reviewers still need a synthesized explanation for creation-time queries, existing-instance queries, lifecycle methods, event methods, activity methods, formulas, triggers, and collection iteration.
• The runtime audit specifically flagged TemplateActivator.Create / actual-scope resolution as a risky area.

5. Collection scope behavior / aggregate accessors / query semantics weak spots

• 08-collections-and-propagation.md establishes the collection model well, but several review-critical semantics are still thin:
  • collection hook host responsibility
  • anonymous collection scope lifecycle expectations
  • aggregate accessor edge cases
  • collection iteration/query behavior versus contract-wide iteration
  • query forms that are live-contract examples but still effectively untested

6. on_action scope declaration semantics

• 04-behavior.md documents event trigger subscription shape, but the declaration semantics for on_action itself are still weaker than they should be for review.
• The live docs need a clearer statement of scope declaration, provided scope expectations, firing-site obligations, and ordering/selection implications.

7. WalkScope contract synthesis

• 01-world-shape.md and 05-expressions.md cover walks_to and WalkScope, but the end-to-end contract is still fragmented.
• The runtime audit highlighted risk around self-walk, declared multi-hop behavior, and enforcement of the effective walk graph.
• Reviewers need one explicit section that answers: what is legal, what is host-defined, what must be declared, and what should fail.

8. Provided-scope and scope-slot enforcement uncertainty

• The runtime audit surfaced uncertainty around provided-scope enforcement and scope slot guarantees.
• Current docs describe the surfaces, but do not yet give a compact review-level statement of enforcement timing, failure mode, and trust boundary.

Adjacent Semantic Gaps

These are not purely scope-doc issues, but they materially affect review of scope and runtime meaning.

• registry_only still gap. Live docs describe the intended feature, but end-to-end implementation/enforcement is still missing.
• Dynamic formula capture / captured1 gap. Dynamic modifier effects and formula re-evaluation still do not fully honor captured outer-scope semantics.
• DestroyEntityWithChildren not implemented. Documented target shape exists, but runtime support is still pending.
• Scope-field clamp enforcement underspecified. 01-world-shape.md notes that scope-field clamps are effectively spec-only in current runtime shape.
• ResourceProductionSystem frequency/perf issue. Still called out as missing frequency/distribution behavior and a performance concern.
• Upgrade syntax/source docs missing. The audits surfaced this as adjacent missing author-facing documentation.
• Typed activity args source syntax missing. Runtime/data shape is described better than the final source-level authoring surface.
• Scope-method source/lowering examples incomplete. Metadata and typed-callable pieces are present, but the reviewable end-to-end examples are still thin.
• auto_modifier only in deferred ideas. Not a live committed source surface.
• SECS0822 / diagnostic-map gap. The old diagnostic renumbering history exists, but the live diagnostic map is still not consolidated enough for reviewers.
• Dynamic effect capture remains semantically risky even where docs mention the intended shape.
• Archive-removal aftermath exposed missing synthesis, not just missing files.

Risk / Priority

Highest-risk gaps

1. captured0 / captured1 semantics

   • Highest semantic risk.
   • Affects trigger re-evaluation, dynamic effects, nested iteration, and root/prev meaning.
   • Current generated/runtime evidence still includes null capture behavior where real captures are expected.

2. TemplateActivator actual-scope / root-scope behavior

   • High risk because call-site semantics differ between creation-time and existing-instance paths.
   • Reviewers need confidence that docs match runtime activation/query behavior.

3. Collection hook host responsibility

   • High risk because collection hooks are described as compiler/runtime shape, but actual host obligations are still easy to misread.

4. WalkScope contract

   • High risk because it is foundational to all scope access.
   • Includes self-walk, multi-hop, declared-edge enforcement, and null/failure behavior.

5. ProvidedScopes / provided-scope enforcement uncertainty

   • High risk because mismatched assumptions here can make on-action and dispatch behavior look documented when it is not actually enforced.

6. Query forms that are documented but effectively untested

   • any, every, count, first, random lowerings are live-contract examples, but the runtime audit flagged them as not yet well-proven by content/tests.

Medium-risk gaps

• registry_only
• typed activity args source syntax
• scope-method author-facing examples
• upgrade syntax/source docs
• diagnostic-map consolidation
• scope-field clamp enforcement wording

Lower but still relevant

• auto_modifier remaining deferred-only
• ResourceProductionSystem frequency/perf documentation drift once main scope semantics are clarified

Recommended Doc-Expansion Order

Carried forward from the audit prioritization, the recommended expansion order is:

1. 05-expressions.md

   • First priority because it is the practical scope-semantics hub.
   • Expand scope-frame matrix, root/prev capture, creation-time vs existing-instance behavior, null-walk rules, saved-scope examples, and query-form caveats.

2. 08-collections-and-propagation.md

   • Next because collection scopes, aggregate accessors, hook responsibility, registry[id], and query/iteration semantics are a major adjacent gap cluster.

3. 04-behavior.md

   • Expand on_action declaration semantics, saved-scope/dispatch examples, upgrade syntax references, and activity-facing scope examples.

4. 03-channels-and-modifiers.md

   • Tighten trigger/formula capture rules, dynamic effect capture semantics, and explicit non-implemented/runtime-gap statements.

5. 01-world-shape.md

   • Clarify walk graph contract, self-walk/multi-hop expectations, scope declarations, and enforcement boundaries.

6. 07-structured-template-data-and-callables.md

   • Fill in scope-method authoring and lowering examples; connect typed callable semantics to the scope docs more directly.

7. 06-overrides-and-modding.md

   • Clean up diagnostic-map references and any merge-surface wording that now depends on later scope/behavior clarifications.

8. 09-ai-policies-and-activities.md

   • Finish typed activity args source syntax and any activity-facing scope examples that remain underexplained.

9. 10-host-secs-execution-boundary.md

   • Use as the cleanup pass for host-responsibility clarifications after the higher-priority semantic docs are expanded.

10. FUTURE_WORK.md

• Keep aligned as items are promoted, deferred, or explicitly left as backlog.

Review Questions / Decisions Pending

This packet is waiting for user instructions on what to do next. In particular:

• Which of these findings should be promoted into live numbered docs now?
• Which items should be specified as normative contract even if runtime/tests are not complete yet?
• Which items should remain explicitly backlog-only in FUTURE_WORK.md?
• Which gaps should get examples only, versus full semantic sections?
• Whether the next pass should focus on scope semantics only, or bundle the adjacent semantic gaps at the same time.

Consolidated Findings Snapshot

For later review, the two audits together support the following working conclusion:

• The live numbered docs are already the authority, but they behave more like lowering-contract fragments than a synthesized scope reference.
• Scope semantics are currently distributed across 00-overview.md, 01-world-shape.md, 03-channels-and-modifiers.md, 04-behavior.md, 05-expressions.md, 07-structured-template-data-and-callables.md, and 08-collections-and-propagation.md.
• The runtime/tests/generated layer already provides real semantic evidence for ScopeDeclaration, ScopeFrame, WalkScope, collections, scope slots, saved scopes, contract query/method calls, and query keywords.
• The most important remaining review task is deciding what to elevate into clearer live documentation versus what to leave as explicit future/runtime backlog.