note001

Here’s a structured prediction of the interaction surface — the key touchpoints and responsibilities — for:

• 👷 Template Developer: you (or someone extending the core template logic)
• 🧩 Template Consuming Developer: a project developer using the template to implement a specific Maestro BPMN task

---

🧭 Interaction Surface Table

Surface / Responsibility	👷 Template Developer	🧩 Consuming Developer
Request Argument	Defines its schema (Request.cs, request-schema.v1.json)	Reads from it (req.RequestBody.Payload)
Request Deserialization	Provides scaffolding (RequestDeserializer.cs)	Implements domain-specific logic to parse payload
req Variable	Initializes and injects via Invoke Code or deserializer	Uses frequently in processing logic
Business Logic (Processing.xaml)	Sets up call structure (e.g. invokes subworkflow)	Fills in the real logic per use case
res / resp Variables	Defines structure (Response.cs, Result optional)	Assigns meaningful result data
stat Variable	Initializes early (default failure)	Updates via StatusBuilder.SetSuccess or .SetRetryable(...)
StatusBuilder Usage	Maintains it, provides API surface	Calls SetSuccess, SetRetryable, or Create(...)
Logging / Tracing	May scaffold generic logging calls	Logs contextually meaningful info (e.g. payload ID)
Dogfooding Mode	Implements random scenario switcher	Usually doesn't modify this (except to debug template)
Unit Tests / TestCase Excel	Provides schema-aligned test rows, validation tools	Extends rows with real use cases, expected assertions
Input Schema Evolution (v1 → v2)	Maintains versioned schemas and adapters	Adapts payload if migrating to new schema
MainEntrypoint.xaml Structure	Owns root-level design (Initialize, Validate, Processing, Teardown)	Navigates and injects business logic into Processing
Custom Fields in status.details	Optionally normalizes or enriches	Adds workflow-specific context (e.g. recordsFound)
Exception Handling	Provides default global handler using StatusBuilder	Leverages or overrides with domain-specific logic

---

✅ Key Insights

• The template developer focuses on infrastructure, scaffolding, and guarantees (validation, schema contracts, extensibility).

• The consuming developer focuses on business logic, actual payload interpretation, and outcome setting.

• The common handshake happens via:

  • req, res, stat variables
  • Request.cs, Status.cs, Response.cs
  • the status contract and StatusBuilder API

---

Would you like this rendered as Markdown or into a doc comment block in the README for future contributors?