186 lines
6.7 KiB
Markdown
Executable File
186 lines
6.7 KiB
Markdown
Executable File
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: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`)
|
|
```python
|
|
# [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`)
|
|
```html
|
|
<!-- [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)
|
|
|
|
Contracts define *what* the code does before *how* it does it.
|
|
|
|
### 1. Python Contract Style
|
|
Uses comment blocks inside the anchor.
|
|
|
|
```python
|
|
# [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:Function]
|
|
```
|
|
|
|
### 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.
|
|
|
|
```javascript
|
|
// [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:Function]
|
|
```
|
|
|
|
---
|
|
|
|
## 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. |