ss-tools/semantic_protocol.md

Here is the revised System Standard, adapted for a Polyglot environment (Python Backend + Svelte Frontend) and removing the requirement for explicit assertion generation.

This protocol standardizes the "Semantic Bridge" between the two languages using unified Anchor logic while respecting the native documentation standards (Comments for Python, JSDoc for JavaScript/Svelte).

---

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]
• Svelte (Top-level):
  • Start: <!-- [DEF:ComponentName:Component] -->
  • End: <!-- [/DEF:ComponentName] -->
• Svelte (Script/JS/TS):
  • Start: // [DEF:funcName:Function]
  • End: // [/DEF:funcName]

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]

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]

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

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

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

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

---

IV. CONTRACTS (Design by Contract)

Contracts define what the code does before how it does it.

1. Python Contract Style

Uses comment blocks inside the anchor.

# [DEF:calculate_total:Function]
# @PURPOSE: Calculates cart total including tax.
# @PRE:     items list is not empty.
# @POST:    returns non-negative Decimal.
# @PARAM:   items (List[Item]) - Cart items.
# @RETURN:  Decimal - Final total.
def calculate_total(items: List[Item]) -> Decimal:
    # Logic implementation that respects @PRE
    if not items:
        return Decimal(0)
        
    # ... calculation ...
    
    # Logic ensuring @POST
    return total
# [/DEF:calculate_total]

2. Svelte/JS Contract Style (JSDoc)

Uses JSDoc blocks inside the anchor. Standard JSDoc tags are used where possible; custom GRACE tags are added for strictness.

// [DEF:updateUserProfile:Function]
/**
 * @purpose Updates user data in the store and backend.
 * @pre     User must be authenticated (session token exists).
 * @post    UserStore is updated with new data.
 * @param   {Object} profileData - The new profile fields.
 * @returns {Promise<void>}
 * @throws  {AuthError} If session is invalid.
 */
// @RELATION: CALLS -> api.user.update
async function updateUserProfile(profileData) {
    // Logic implementation
    if (!session.token) throw new AuthError();
    
    // ...
}
// [/DEF:updateUserProfile]

---

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. 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.