ss-tools/semantic_protocol.md

SYSTEM STANDARD: POLYGLOT CODE GENERATION PROTOCOL (GRACE-Poly)

OBJECTIVE: Generate Python and Svelte/TypeScript code that strictly adheres to Semantic Coherence standards. Output must be machine-readable, fractal-structured, and optimized for Sparse Attention navigation.

I. CORE REQUIREMENTS

1. Causal Validity: Semantic definitions (Contracts) must ALWAYS precede implementation code.
2. Immutability: Architectural decisions defined in the Module/Component Header are treated as immutable constraints.
3. Format Compliance: Output must strictly follow the [DEF:..:...] / [/DEF:...:...] anchor syntax for structure.
4. Logic over Assertion: Contracts define the logic flow. Do not generate explicit assert statements unless requested. The code logic itself must inherently satisfy the Pre/Post conditions (e.g., via control flow, guards, or types).
5. Fractal Complexity: Modules and functions must adhere to strict size limits (~300 lines/module, ~30-50 lines/function) to maintain semantic focus.

---

II. SYNTAX SPECIFICATION

Code structure is defined by Anchors (square brackets). Metadata is defined by Tags (native comment style).

1. Entity Anchors (The "Container")

Used to define the boundaries of Modules, Classes, Components, and Functions.

• Python:
  • Start: # [DEF:identifier:Type]
  • End: # [/DEF:identifier:Type]
• Svelte (Top-level):
  • Start: <!-- [DEF:ComponentName:Component] -->
  • End: <!-- [/DEF:ComponentName:Component] -->
• Svelte (Script/JS/TS):
  • Start: // [DEF:funcName:Function]
  • End: // [/DEF:funcName:Function]

Types: Module, Component, Class, Function, Store, Action.

2. Graph Relations (The "Map")

Defines high-level dependencies.

• Python Syntax: # @RELATION: TYPE -> TARGET_ID
• Svelte/JS Syntax: // @RELATION: TYPE -> TARGET_ID
• Types: DEPENDS_ON, CALLS, INHERITS_FROM, IMPLEMENTS, BINDS_TO, DISPATCHES.

---

III. FILE STRUCTURE STANDARD

1. Python Module Header (.py)

# [DEF:module_name:Module]
#
# @SEMANTICS: [keywords for vector search]
# @PURPOSE:   [Primary responsibility of the module]
# @LAYER:     [Domain/Infra/API]
# @RELATION:  [Dependencies]
#
# @INVARIANT: [Global immutable rule]
# @CONSTRAINT: [Hard restriction, e.g., "No ORM calls here"]

# [SECTION: IMPORTS]
...
# [/SECTION]

# ... IMPLEMENTATION ...

# [/DEF:module_name:Module]

2. Svelte Component Header (.svelte)

<!-- [DEF:ComponentName:Component] -->
<!--
@SEMANTICS: [keywords]
@PURPOSE:   [Primary UI responsibility]
@LAYER:     [Feature/Atom/Layout]
@RELATION:  [Child components, Stores]

@INVARIANT: [UI rules, e.g., "Always responsive"]
-->

<script lang="ts">
  // [SECTION: IMPORTS]
  // ...
  // [/SECTION: IMPORTS]

  // ... LOGIC IMPLEMENTATION ...
</script>

<!-- [SECTION: TEMPLATE] -->
...
<!-- [/SECTION: TEMPLATE] -->

<style>
  /* ... */
</style>

<!-- [/DEF:ComponentName:Component] -->

---

IV. CONTRACTS (Design by Contract & Semantic Control)

Contracts are the Source of Truth and the Control Vector for the code. They must be written with high semantic density to ensure the LLM fully "understands" the function's role within the larger Graph without needing to read the implementation body.

1. The Anatomy of a Semantic Contract

Every contract must answer three questions for the AI Agent:

1. Intent: Why does this exist? (Vector alignment)
2. Boundaries: What are the constraints? (Pre/Post/Invariants)
3. Dynamics: How does it change the system state? (Side Effects/Graph)

Standard Tags Taxonomy:

• @PURPOSE: (Mandatory) A concise, high-entropy summary of functionality.
• @PRE: (Mandatory) Conditions required before execution. Defines the valid input space.
• @POST: (Mandatory) Conditions guaranteed after execution. Defines the valid output space.
• @PARAM: Input definitions with strict typing.
• @RETURN: Output definition.
• @THROW: Explicit failure modes.
• @SIDE_EFFECT: (Critical) Explicitly lists external state mutations (DB writes, UI updates, events). Vital for "Mental Modeling".
• @INVARIANT: (Optional) Local rules that hold true throughout the function execution.
• @ALGORITHM: (Optional) For complex logic, briefly describes the strategy (e.g., "Two-pointer approach", "Retry with exponential backoff").
• @RELATION: (Graph) Edges to other nodes (CALLS, DISPATCHES, DEPENDS_ON).

---

2. Python Contract Style (.py)

Uses structured comment blocks inside the anchor. Focuses on type hints and logic flow guards.

# [DEF:process_order_batch:Function]
# @PURPOSE:     Orchestrates the validation and processing of a batch of orders.
#               Ensures atomic processing per order (failure of one does not stop others).
#
# @PRE:         batch_id must be a valid UUID string.
# @PRE:         orders list must not be empty.
# @POST:        Returns a dict mapping order_ids to their processing status (Success/Failed).
# @INVARIANT:   The length of the returned dict must equal the length of input orders.
#
# @PARAM:       batch_id (str) - The unique identifier for the batch trace.
# @PARAM:       orders (List[OrderDTO]) - List of immutable order objects.
# @RETURN:      Dict[str, OrderStatus] - Result map.
#
# @SIDE_EFFECT: Writes audit logs to DB.
# @SIDE_EFFECT: Publishes 'ORDER_PROCESSED' event to MessageBus.
#
# @RELATION:    CALLS -> InventoryService.reserve_items
# @RELATION:    CALLS -> PaymentGateway.authorize
# @RELATION:    WRITES_TO -> Database.AuditLog
def process_order_batch(batch_id: str, orders: List[OrderDTO]) -> Dict[str, OrderStatus]:
    # 1. Structural Guard Logic (Handling @PRE)
    if not orders:
        return {}
    
    # 2. Implementation with @INVARIANT in mind
    results = {}
    
    for order in orders:
        # ... logic ...
        pass

    # 3. Completion (Logic naturally satisfies @POST)
    return results
# [/DEF:process_order_batch:Function]

3. Svelte/JS Contract Style (JSDoc++)

Uses enhanced JSDoc. Since JS is less strict than Python, the contract acts as a strict typing and behavioral guard.

// [DEF:handleUserLogin:Function]
/**
 * @purpose Authenticates the user and synchronizes the local UI state.
 *          Handles the complete lifecycle from form submission to redirection.
 *
 * @pre     LoginForm must be valid (validated by UI constraints).
 * @pre     Network must be available (optimistic check).
 * @post    SessionStore contains a valid JWT token.
 * @post    User is redirected to the Dashboard.
 *
 * @param   {LoginCredentials} credentials - Email and password object.
 * @returns {Promise<void>}
 * @throws  {NetworkError} If API is unreachable.
 * @throws  {AuthError} If credentials are invalid (401).
 *
 * @side_effect Updates global $session store.
 * @side_effect Clears any existing error toasts.
 *
 * @algorithm   1. Set loading state -> 2. API Call -> 3. Decode Token -> 4. Update Store -> 5. Redirect.
 */
// @RELATION: CALLS -> api.auth.login
// @RELATION: MODIFIES_STATE_OF -> stores.session
// @RELATION: DISPATCHES -> 'toast:success'
async function handleUserLogin(credentials) {
    // 1. Guard Clause (@PRE)
    if (!isValid(credentials)) return;

    try {
        // ... logic ...
    } catch (e) {
        // Error handling (@THROW)
    }
}
// [/DEF:handleUserLogin:Function]

---

4. Semantic Rules for Contracts

1. Completeness: A developer (or Agent) must be able to write the function body solely by reading the Contract, without guessing.
2. No Implementation Leakage: Describe what happens, not how (unless using @ALGORITHM for complexity reasons). E.g., say "Persists user" instead of "Inserts into users table via SQL".
3. Active Voice: Use active verbs (Calculates, Updates, Enforces) to stronger vector alignment.
4. Graph Connectivity: The @RELATION tags must explicitly link to other [DEF:...] IDs existing in the codebase. This builds the navigation graph for RAG.

---

V. LOGGING STANDARD (BELIEF STATE)

Logs delineate the agent's internal state.

• Python: MUST use a Context Manager (e.g., with belief_scope("ANCHOR_ID"):) to ensure state consistency and automatic handling of Entry/Exit/Error states.
  • Manual logging (inside scope): logger.info(f"[{ANCHOR_ID}][{STATE}] Msg")
• Svelte/JS: console.log(\[${ANCHOR_ID}][${STATE}] Msg`)`

Required States:

1. Entry (Start of block - Auto-logged by Context Manager)
2. Action (Key business logic - Manual log)
3. Coherence:OK (Logic successfully completed - Auto-logged by Context Manager)
4. Coherence:Failed (Exception/Error - Auto-logged by Context Manager)
5. Exit (End of block - Auto-logged by Context Manager)

---

VI. FRACTAL COMPLEXITY LIMIT

To maintain semantic coherence and avoid "Attention Sink" issues:

• Module Size: If a Module body exceeds ~300 lines (or logical complexity), it MUST be refactored into sub-modules or a package structure.
• Function Size: Functions should fit within a standard attention "chunk" (approx. 30-50 lines). If larger, logic MUST be decomposed into helper functions with their own contracts.

This ensures every vector embedding remains sharp and focused.

---

VII. GENERATION WORKFLOW

1. Context Analysis: Identify language (Python vs Svelte) and Architecture Layer.
2. Scaffolding: Generate the [DEF:...:...] Anchors and Header/Contract before writing any logic.
3. Implementation: Write the code. Ensure the code logic handles the @PRE conditions (e.g., via if/return or guards) and satisfies @POST conditions naturally. Do not write explicit assert statements unless debugging mode is requested.
4. Closure: Ensure every [DEF:...:...] is closed with [/DEF:...:...] to accumulate semantic context.