generated from coulomb/repo-seed
Seeded repo with intent and specs
This commit is contained in:
224
INTENT.md
Normal file
224
INTENT.md
Normal file
@@ -0,0 +1,224 @@
|
|||||||
|
# INTENT.md
|
||||||
|
|
||||||
|
## Project Name
|
||||||
|
|
||||||
|
**coordination-engine**
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
`coordination-engine` is a generalized framework and runtime for digital coordination as goal- and result-driven communication between multiple interacting parties.
|
||||||
|
|
||||||
|
It provides the foundation for building scenario-specific, headless coordination applications by selecting and composing only the relevant concepts from the framework: participants, intended results, payloads, action surfaces, access, notifications, deliveries, interactions, evidence, policies, and adapters.
|
||||||
|
|
||||||
|
The core idea is that digital coordination is not primarily about transporting messages from sender to receiver. It is about managing access, enabling interactions, observing evidence, and applying follow-up policies until an intended result is achieved, failed, expired, escalated, or manually closed.
|
||||||
|
|
||||||
|
## Primary Utility
|
||||||
|
|
||||||
|
`coordination-engine` helps developers and agents build applications that coordinate people, organizations, systems, payloads, and actions across multiple channels and technologies.
|
||||||
|
|
||||||
|
It is intended for scenarios such as:
|
||||||
|
|
||||||
|
* digital postal delivery
|
||||||
|
* secure document access
|
||||||
|
* document and data collection
|
||||||
|
* AGB / terms acceptance
|
||||||
|
* contract signing and closing
|
||||||
|
* invoice and payment collection
|
||||||
|
* incident acknowledgement
|
||||||
|
* approval workflows
|
||||||
|
* onboarding processes
|
||||||
|
* regulated communication and evidence tracking
|
||||||
|
|
||||||
|
The engine should make these scenarios easier to implement by providing reusable coordination primitives instead of requiring every application to reinvent notification logic, delivery tracking, participant state, evidence handling, and follow-up rules.
|
||||||
|
|
||||||
|
## Strategic Role
|
||||||
|
|
||||||
|
`coordination-engine` is the implementation project for the broader **coordination-framework**.
|
||||||
|
|
||||||
|
It should become a headless coordination runtime that can be embedded into or integrated with specialized applications. These applications may expose their own user interfaces, portals, workflows, APIs, or agent interfaces while relying on `coordination-engine` for the underlying coordination logic.
|
||||||
|
|
||||||
|
The project is strategically positioned between notification systems, workflow engines, document delivery platforms, campaign automation tools, signature systems, payment systems, and evidence/audit infrastructure.
|
||||||
|
|
||||||
|
It is not meant to replace all of these systems. Instead, it provides the coordination layer that can orchestrate them through adapters.
|
||||||
|
|
||||||
|
## Core Principle
|
||||||
|
|
||||||
|
A coordination case is successful when its intended result is satisfied, not when messages have merely been sent.
|
||||||
|
|
||||||
|
Digital coordination is the controlled arrangement of participants, payloads, access, notifications, deliveries, interactions, and evidence so that intended results can be achieved under uncertainty.
|
||||||
|
|
||||||
|
## Conceptual Scope
|
||||||
|
|
||||||
|
The project revolves around the following core concepts.
|
||||||
|
|
||||||
|
### CoordinationCase
|
||||||
|
|
||||||
|
A goal-directed coordination process initiated by one party to achieve an intended result involving one or more participants.
|
||||||
|
|
||||||
|
### Participant
|
||||||
|
|
||||||
|
An actor involved in the coordination case, such as an initiator, recipient, respondent, signer, payer, approver, delegate, organization, system, agent, or intermediary.
|
||||||
|
|
||||||
|
### IntendedResult
|
||||||
|
|
||||||
|
The result the initiator wants to achieve, such as payload access, valid submission, acceptance, signature, payment, acknowledgement, or completion.
|
||||||
|
|
||||||
|
### Payload
|
||||||
|
|
||||||
|
A meaningful resource involved in coordination, such as a document, contract, invoice, form, payment request, data package, submitted artifact, or receipt.
|
||||||
|
|
||||||
|
### ActionSurface
|
||||||
|
|
||||||
|
The place where participants interact with the case, such as a portal page, app screen, payment page, signature flow, upload form, approval screen, chatbot, API endpoint, or message reply interface.
|
||||||
|
|
||||||
|
### Notification
|
||||||
|
|
||||||
|
An awareness-oriented communication act that prompts attention or action.
|
||||||
|
|
||||||
|
### Delivery
|
||||||
|
|
||||||
|
The controlled availability, access, transfer, retrieval, submission, or consumption of a payload.
|
||||||
|
|
||||||
|
### Interaction
|
||||||
|
|
||||||
|
A meaningful action performed by a participant, system, agent, or intermediary on a payload or action surface.
|
||||||
|
|
||||||
|
### EvidenceEvent
|
||||||
|
|
||||||
|
A normalized observation used to assess progress, uncertainty, success, failure, or required follow-up.
|
||||||
|
|
||||||
|
### Policy
|
||||||
|
|
||||||
|
A rule set that interprets evidence and determines next actions such as waiting, notifying, reminding, retrying, escalating, switching channels, requesting correction, revoking access, closing, or failing.
|
||||||
|
|
||||||
|
## Intended Architecture Direction
|
||||||
|
|
||||||
|
The runtime should be organized around a central **coordination-controller** supported by specialized controllers and services:
|
||||||
|
|
||||||
|
* `coordination-controller`
|
||||||
|
* `result-controller`
|
||||||
|
* `participant-controller`
|
||||||
|
* `payload-controller`
|
||||||
|
* `access-controller`
|
||||||
|
* `notification-controller`
|
||||||
|
* `delivery-controller`
|
||||||
|
* `interaction-controller`
|
||||||
|
* `identity-authority-controller`
|
||||||
|
* `evidence-ledger`
|
||||||
|
* `policy-engine`
|
||||||
|
* `adapter-layer`
|
||||||
|
|
||||||
|
The architecture should remain headless, API-first, event-aware, and adapter-friendly.
|
||||||
|
|
||||||
|
## Scenario Composition
|
||||||
|
|
||||||
|
The framework should allow scenario-specific applications to use only the concepts they need.
|
||||||
|
|
||||||
|
A simple notification-and-access scenario should not need payment, signature, or document-validation functionality.
|
||||||
|
|
||||||
|
A contract-signing scenario should be able to select stronger identity, authority, payload-integrity, signature, and evidence requirements.
|
||||||
|
|
||||||
|
A payment-collection scenario should be able to integrate invoice payloads, payment action surfaces, payment-provider events, reminders, disputes, and dunning escalation.
|
||||||
|
|
||||||
|
This selective composition is central to the project.
|
||||||
|
|
||||||
|
## Primary Users
|
||||||
|
|
||||||
|
The project is intended for:
|
||||||
|
|
||||||
|
* developers building coordination applications
|
||||||
|
* product teams defining communication-heavy business processes
|
||||||
|
* operations teams monitoring unresolved coordination cases
|
||||||
|
* compliance and legal stakeholders reviewing evidence
|
||||||
|
* automation agents creating, inspecting, and updating cases
|
||||||
|
* integration partners connecting channel, identity, payment, signature, document, CRM, ERP, or messaging systems
|
||||||
|
|
||||||
|
## Design Priorities
|
||||||
|
|
||||||
|
The project should prioritize:
|
||||||
|
|
||||||
|
1. **Result orientation**
|
||||||
|
Model success through intended result satisfaction, not message dispatch.
|
||||||
|
|
||||||
|
2. **Headless operation**
|
||||||
|
Provide APIs and events rather than a fixed UI.
|
||||||
|
|
||||||
|
3. **Evidence-driven state**
|
||||||
|
Preserve observations and derive assessments from evidence.
|
||||||
|
|
||||||
|
4. **Uncertainty awareness**
|
||||||
|
Treat ambiguous states as first-class, especially where channel evidence is weak.
|
||||||
|
|
||||||
|
5. **Adapter extensibility**
|
||||||
|
Support many protocols, systems, and providers through normalized actions and events.
|
||||||
|
|
||||||
|
6. **Scenario modularity**
|
||||||
|
Allow applications to select the relevant subset of concepts.
|
||||||
|
|
||||||
|
7. **Auditability**
|
||||||
|
Explain why a participant or case was marked successful, failed, partial, expired, escalated, or unresolved.
|
||||||
|
|
||||||
|
8. **Agent-friendliness**
|
||||||
|
Provide clear schemas, APIs, events, and state models suitable for automation.
|
||||||
|
|
||||||
|
## Initial Implementation Focus
|
||||||
|
|
||||||
|
The first implementation should prove the core abstraction with a minimal but useful scenario.
|
||||||
|
|
||||||
|
Recommended MVP focus:
|
||||||
|
|
||||||
|
* create a coordination case
|
||||||
|
* add multiple participants
|
||||||
|
* register one payload
|
||||||
|
* define an intended result
|
||||||
|
* create participant-specific access grants
|
||||||
|
* record simulated or real notification events
|
||||||
|
* record access and interaction evidence
|
||||||
|
* derive participant-level state
|
||||||
|
* derive case-level progress
|
||||||
|
* generate follow-up actions from policy
|
||||||
|
* close the case based on sufficient evidence
|
||||||
|
|
||||||
|
The first real adapters should likely be:
|
||||||
|
|
||||||
|
* email adapter
|
||||||
|
* portal/action-surface adapter
|
||||||
|
* webhook adapter
|
||||||
|
|
||||||
|
Simulated adapters are acceptable for proving the core runtime.
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
`coordination-engine` is not primarily:
|
||||||
|
|
||||||
|
* an email sending system
|
||||||
|
* a newsletter platform
|
||||||
|
* a campaign marketing tool
|
||||||
|
* a document management system
|
||||||
|
* a payment processor
|
||||||
|
* a signature provider
|
||||||
|
* a CRM
|
||||||
|
* an ERP
|
||||||
|
* a full workflow/BPMN engine
|
||||||
|
* a legal proof system by default
|
||||||
|
|
||||||
|
It may integrate with these systems, but its role is to coordinate result-oriented interaction across them.
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
The project is successful when a developer can define a scenario-specific headless coordination application by composing framework concepts and policies, without hardcoding all coordination logic from scratch.
|
||||||
|
|
||||||
|
The first useful version should demonstrate:
|
||||||
|
|
||||||
|
* multi-participant coordination
|
||||||
|
* evidence-driven state changes
|
||||||
|
* distinction between notification, delivery, access, and interaction
|
||||||
|
* ambiguous or unresolved states
|
||||||
|
* policy-based follow-up actions
|
||||||
|
* result-based closure
|
||||||
|
* traceability from final assessment to evidence events
|
||||||
|
|
||||||
|
## Guiding Statement
|
||||||
|
|
||||||
|
`coordination-engine` coordinates participants around payloads and action surfaces through notifications, deliveries, interactions, access control, evidence, and policies to achieve intended results under uncertainty.
|
||||||
|
|
||||||
1342
history/260601-AdapterInterfaceSpecification.md
Normal file
1342
history/260601-AdapterInterfaceSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1787
history/260601-HybridmailAdapterSpecification.md
Normal file
1787
history/260601-HybridmailAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1412
history/260601-RuntimeArchitectureAndAdapterSubsystem.md
Normal file
1412
history/260601-RuntimeArchitectureAndAdapterSubsystem.md
Normal file
File diff suppressed because it is too large
Load Diff
1991
spec/AdapterInterfaceSpecification.md
Normal file
1991
spec/AdapterInterfaceSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1520
spec/EmailAdapterSpecification.md
Normal file
1520
spec/EmailAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
925
spec/HybridMailProviderApiComparison.md
Normal file
925
spec/HybridMailProviderApiComparison.md
Normal file
@@ -0,0 +1,925 @@
|
|||||||
|
# HybridMailProviderApiComparison.md
|
||||||
|
|
||||||
|
## 1. Document Status
|
||||||
|
|
||||||
|
**Document:** HybridMailProviderApiComparison.md
|
||||||
|
**Project:** hybridmail-connect
|
||||||
|
**Related Specifications:**
|
||||||
|
|
||||||
|
* `HybridmailAdapterSpecification.md`
|
||||||
|
* `HybridmailBinectSpecification.md`
|
||||||
|
* `HybridmailPingenSpecification.md`
|
||||||
|
* `HybridmailDpagSpecification.md`
|
||||||
|
* `AdapterInterfaceSpecification.md`
|
||||||
|
|
||||||
|
**Status:** Draft v1.0
|
||||||
|
**Scope:** Provider API comparison, SWOT-style assessment, implementation implications, and coding-agent friendliness.
|
||||||
|
|
||||||
|
## 2. Purpose
|
||||||
|
|
||||||
|
This document compares three hybrid-mail provider APIs and provider-flavor candidates for `hybridmail-connect`:
|
||||||
|
|
||||||
|
* Binect
|
||||||
|
* Pingen
|
||||||
|
* Deutsche Post / E-POSTBUSINESS API / DPAG Hybrid Mail Shipments E-POST
|
||||||
|
|
||||||
|
The comparison focuses on their suitability as provider flavors for a generalized `hybridmail-connect` adapter that integrates with `coordination-engine`.
|
||||||
|
|
||||||
|
The goal is not to pick a single winner, but to understand:
|
||||||
|
|
||||||
|
* common baseline capabilities
|
||||||
|
* provider-specific strengths
|
||||||
|
* provider-specific risks and gaps
|
||||||
|
* evidence-model implications
|
||||||
|
* adapter implementation complexity
|
||||||
|
* coding-agent friendliness
|
||||||
|
* how public API digestability could be improved
|
||||||
|
|
||||||
|
## 3. Executive Summary
|
||||||
|
|
||||||
|
All three providers support the core hybrid-mail pattern:
|
||||||
|
|
||||||
|
```text
|
||||||
|
digital document submission
|
||||||
|
→ provider-side validation / preparation
|
||||||
|
→ physical production
|
||||||
|
→ postal dispatch
|
||||||
|
→ status or delivery/return evidence where available
|
||||||
|
```
|
||||||
|
|
||||||
|
However, they differ in emphasis:
|
||||||
|
|
||||||
|
| Provider | Strongest apparent API/product emphasis |
|
||||||
|
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| **Binect** | Document-centric business-letter workflow with upload, attachments, preview, validation, sending, and status queries. |
|
||||||
|
| **Pingen** | Developer-friendly letter API with SDKs, idempotency, Track & Trace, webhooks, staging, send limits, and return-mail processing. |
|
||||||
|
| **DPAG / E-POSTBUSINESS** | Deutsche Post-native hybrid-mail infrastructure with PDF/PDF-A shipment submission, bulk upload, production data, shipment tracking, registered-mail use cases, positioning aids, cover sheets, and scheduled dispatch. |
|
||||||
|
|
||||||
|
For `hybridmail-connect`, the best baseline design is a superset model with provider-specific capability descriptors. No provider flavor should be treated as the normative model. Instead, each provider should map into the generic lifecycle:
|
||||||
|
|
||||||
|
```text
|
||||||
|
uploaded
|
||||||
|
accepted
|
||||||
|
validated
|
||||||
|
ready
|
||||||
|
submitted
|
||||||
|
processing
|
||||||
|
production_started
|
||||||
|
production_completed
|
||||||
|
postal_handover
|
||||||
|
in_transit
|
||||||
|
delivery_confirmed
|
||||||
|
undeliverable
|
||||||
|
return_received
|
||||||
|
status_unknown
|
||||||
|
```
|
||||||
|
|
||||||
|
The most important evidence principle remains:
|
||||||
|
|
||||||
|
> Ordinary hybrid-mail APIs usually provide strong evidence of digital submission, validation, production, or postal dispatch. They do not automatically prove human awareness or legal receipt.
|
||||||
|
|
||||||
|
## 4. Source Basis and Confidence
|
||||||
|
|
||||||
|
This comparison is based on public provider information and public developer/API materials.
|
||||||
|
|
||||||
|
### Binect
|
||||||
|
|
||||||
|
Public Binect API information confirms a REST/Swagger API for business-letter dispatch, document upload, attachments, print/shipping options, preview, sending, document status, shipping status, validation of address position/address format/restricted areas, and full-service print/enveloping/franking/dispatch. The public Swagger page exposes Binect API concepts and validation descriptions, while the Binect API page positions it as an integration API for document dispatch.
|
||||||
|
|
||||||
|
### Pingen
|
||||||
|
|
||||||
|
Pingen publicly emphasizes a developer-friendly Letter API with SDKs for PHP, Python, Go, and .NET, Idempotency-Key support, rate limiting, configurable send limits, staging/sandbox, Track & Trace, webhooks, document validation, and return-mail processing. Pingen also documents detailed API status information and tracking “from A to Z.”
|
||||||
|
|
||||||
|
### DPAG / E-POSTBUSINESS
|
||||||
|
|
||||||
|
Deutsche Post’s Hybrid Mail Shipments E-POST API documentation states that the E-POSTBUSINESS API expects single PDF documents for mail shipments, supports one-by-one and bulk upload, and provides detailed shipment processing information and bulk status requests. Deutsche Post’s business API material describes REST/Swagger documentation, shipment-level status with production data and shipment tracking, individual-to-mass submission, address-window positioning aids, automatic positioning, individual cover sheets, scheduled dispatch, and hybrid dispatch services.
|
||||||
|
|
||||||
|
### Confidence Notes
|
||||||
|
|
||||||
|
The high-level comparison is reliable. Exact endpoint names, exact status names, native enum values, webhook payload shapes, product availability, account-specific capabilities, and cancellation behavior require validation against the live provider API documentation and target account configuration.
|
||||||
|
|
||||||
|
## 5. Common Baseline Across Providers
|
||||||
|
|
||||||
|
The shared baseline for `hybridmail-connect` should include:
|
||||||
|
|
||||||
|
```text
|
||||||
|
document / PDF payload submission
|
||||||
|
provider-side acceptance
|
||||||
|
document validation
|
||||||
|
address / layout suitability checks
|
||||||
|
print and shipping options
|
||||||
|
sending / submission step
|
||||||
|
status polling or status retrieval
|
||||||
|
production / processing status
|
||||||
|
postal dispatch or handover evidence
|
||||||
|
return / undeliverable evidence where available
|
||||||
|
batch or serial processing where available
|
||||||
|
provider-specific status preservation
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Core Differences at a Glance
|
||||||
|
|
||||||
|
| Dimension | Binect | Pingen | DPAG / E-POSTBUSINESS |
|
||||||
|
| ---------------------------- | -------------------------------------------------- | -------------------------------------- | ------------------------------------------------------- |
|
||||||
|
| API style | REST/Swagger | Developer API with SDKs and docs | REST/Swagger API |
|
||||||
|
| Primary model | Document + sending | Letter + Track & Trace | PDF shipment / mail shipment |
|
||||||
|
| Public developer positioning | Business software / DMS / CRM integration | Strong developer friendliness | Partner/business software integration |
|
||||||
|
| Upload | Document upload | Letter/file creation | PDF shipment upload |
|
||||||
|
| Bulk / serial | Supported / relevant | Supported / relevant | One-by-one and bulk upload |
|
||||||
|
| Attachments | Publicly documented | Provider-specific | Provider-specific |
|
||||||
|
| Preview | Publicly documented | Likely / provider-specific | Provider-specific |
|
||||||
|
| Validation | Address position, address format, restricted areas | Document/letter validation | PDF/PDF-A, address-window, positioning, product/layout |
|
||||||
|
| Idempotency | Adapter-managed unless API support confirmed | Public Idempotency-Key support | Adapter-managed unless API support confirmed |
|
||||||
|
| Webhooks | Provider-specific / unclear publicly | Publicly documented webhook categories | Provider-specific / unclear publicly |
|
||||||
|
| Track & Trace | Status APIs | Strong public emphasis | Publicly documented shipment tracking / production data |
|
||||||
|
| Return mail | Provider-specific | Strong public emphasis | Product/provider-specific |
|
||||||
|
| Registered mail | Provider-specific | Supported/product-dependent | Publicly referenced |
|
||||||
|
| Delivery confirmation | Product-specific | Product-specific | Product-specific |
|
||||||
|
| Scheduled dispatch | Provider-specific | Provider-specific | Publicly referenced |
|
||||||
|
| Address positioning | Validation-oriented | Configurable address position | Positioning aids / automatic positioning |
|
||||||
|
| Cover sheets | Not public baseline | Provider-specific | Publicly referenced |
|
||||||
|
| Coding-agent friendliness | Medium | High | Medium |
|
||||||
|
|
||||||
|
## 7. Provider-Specific Assessment: Binect
|
||||||
|
|
||||||
|
## 7.1 Binect Profile
|
||||||
|
|
||||||
|
Binect appears best modeled as a **document-centric hybrid-mail provider**.
|
||||||
|
|
||||||
|
The workflow centers on:
|
||||||
|
|
||||||
|
```text
|
||||||
|
document upload
|
||||||
|
→ validation
|
||||||
|
→ optional attachments
|
||||||
|
→ print/shipping options
|
||||||
|
→ preview
|
||||||
|
→ sending
|
||||||
|
→ document/shipping status
|
||||||
|
```
|
||||||
|
|
||||||
|
Binect’s public API/Swagger documentation strongly supports the concept of document validation, including address-position, address-format, and restricted-area checks. It also supports attachments and preview retrieval, which makes it attractive for controlled document-dispatch workflows.
|
||||||
|
|
||||||
|
## 7.2 Binect Strengths
|
||||||
|
|
||||||
|
* Strong alignment with business-document dispatch.
|
||||||
|
* Public Swagger/API presence.
|
||||||
|
* Clear document upload and sending workflow.
|
||||||
|
* Public evidence of attachment handling.
|
||||||
|
* Public evidence of preview support.
|
||||||
|
* Validation concerns are visible and practically relevant.
|
||||||
|
* Suitable for DMS, CRM, and business-software integration.
|
||||||
|
* Likely a strong fit for Binect-owned or Binect-adjacent coordination scenarios.
|
||||||
|
|
||||||
|
## 7.3 Binect Weaknesses
|
||||||
|
|
||||||
|
* Public documentation is less marketing-developer-oriented than Pingen.
|
||||||
|
* Publicly available details about webhooks, idempotency, return mail, registered products, and delivery confirmation are less explicit.
|
||||||
|
* Exact native status model must be extracted from the live Swagger/API.
|
||||||
|
* Some concepts may require account-specific or product-specific configuration.
|
||||||
|
* Coding agents may need additional curated examples and mapping tables to avoid guessing.
|
||||||
|
|
||||||
|
## 7.4 Binect Opportunities
|
||||||
|
|
||||||
|
* Strong reference implementation for a German business-letter workflow.
|
||||||
|
* Good fit for `coordination-engine` scenarios involving document validation before dispatch.
|
||||||
|
* Attachments and preview support can support robust approval/review loops.
|
||||||
|
* Validation output can feed a `postal-address-quality` or `document-layout-linting` subsystem.
|
||||||
|
* Could become the first practical provider flavor if the user has strong domain access and Binect-specific knowledge.
|
||||||
|
|
||||||
|
## 7.5 Binect Threats / Risks
|
||||||
|
|
||||||
|
* If exact status semantics are not well documented, agents may over-map provider statuses to strong evidence.
|
||||||
|
* If idempotency is not native, duplicate physical sends must be prevented by the adapter.
|
||||||
|
* If webhooks are missing or not available, polling complexity increases.
|
||||||
|
* If return-mail and registered-letter semantics are not available through API, evidence strength remains limited for high-assurance scenarios.
|
||||||
|
* Provider-specific assumptions could leak into the generic `HybridmailAdapterSpecification.md` if not isolated.
|
||||||
|
|
||||||
|
## 7.6 Binect Implementation Priority
|
||||||
|
|
||||||
|
Recommended implementation priority:
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Document upload
|
||||||
|
2. Validation mapping
|
||||||
|
3. Attachment upload
|
||||||
|
4. Print/shipping options
|
||||||
|
5. Preview retrieval
|
||||||
|
6. Send/submission
|
||||||
|
7. Status polling
|
||||||
|
8. Child/serial document status
|
||||||
|
9. Return/undeliverable mapping if available
|
||||||
|
10. Registered/delivery-confirmation mapping if available
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. Provider-Specific Assessment: Pingen
|
||||||
|
|
||||||
|
## 8.1 Pingen Profile
|
||||||
|
|
||||||
|
Pingen appears best modeled as a **developer-friendly letter API** with strong operational and integration features.
|
||||||
|
|
||||||
|
The workflow centers on:
|
||||||
|
|
||||||
|
```text
|
||||||
|
letter/file creation
|
||||||
|
→ validation
|
||||||
|
→ auto-send or manual send
|
||||||
|
→ Track & Trace
|
||||||
|
→ webhooks
|
||||||
|
→ return-mail / undeliverable / delivered status categories
|
||||||
|
```
|
||||||
|
|
||||||
|
Pingen publicly emphasizes SDKs, Idempotency-Key headers, rate limiting, configurable send limits, staging/sandbox, Track & Trace, and webhooks. This makes it the most coding-agent-friendly provider in the comparison.
|
||||||
|
|
||||||
|
## 8.2 Pingen Strengths
|
||||||
|
|
||||||
|
* Strong developer positioning.
|
||||||
|
* Multi-language SDKs.
|
||||||
|
* Public idempotency support.
|
||||||
|
* Public rate-limit and send-limit support.
|
||||||
|
* Public staging/sandbox or full-feature simulation.
|
||||||
|
* Public Track & Trace emphasis.
|
||||||
|
* Public webhook categories.
|
||||||
|
* Strong return-mail processing story.
|
||||||
|
* Clear API-first product narrative.
|
||||||
|
* Excellent candidate for proving the generic `hybridmail-connect` adapter model.
|
||||||
|
|
||||||
|
## 8.3 Pingen Weaknesses
|
||||||
|
|
||||||
|
* Strong developer story does not remove the need to verify exact webhook payload semantics.
|
||||||
|
* “Delivered” terminology must be interpreted carefully and product-dependently.
|
||||||
|
* Some postal delivery confirmation semantics depend on selected products.
|
||||||
|
* Return-mail evidence can arrive late, requiring robust event-sourcing.
|
||||||
|
* Address-position and validation mapping must still be carefully normalized.
|
||||||
|
|
||||||
|
## 8.4 Pingen Opportunities
|
||||||
|
|
||||||
|
* Best candidate for an external reference provider flavor.
|
||||||
|
* Useful for validating webhook-first and polling-fallback architecture.
|
||||||
|
* Idempotency support can become the model for duplicate-send prevention.
|
||||||
|
* Track & Trace can help define the hybrid-mail timeline API.
|
||||||
|
* Staging/sandbox can support automated integration testing and coding-agent test loops.
|
||||||
|
* Return-mail processing can help define the negative-evidence model.
|
||||||
|
|
||||||
|
## 8.5 Pingen Threats / Risks
|
||||||
|
|
||||||
|
* Overinterpreting Track & Trace events as delivery confirmation.
|
||||||
|
* Treating “sent” as delivered.
|
||||||
|
* Treating product-specific delivered-letter events as generally available.
|
||||||
|
* Assuming webhook categories equal exact coordination event semantics without detailed payload mapping.
|
||||||
|
* Depending too heavily on SDK behavior rather than the underlying API contract.
|
||||||
|
|
||||||
|
## 8.6 Pingen Implementation Priority
|
||||||
|
|
||||||
|
Recommended implementation priority:
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Authentication and workspace/account setup
|
||||||
|
2. Idempotent letter creation
|
||||||
|
3. Validation mapping
|
||||||
|
4. Auto-send/manual-send handling
|
||||||
|
5. Track & Trace polling
|
||||||
|
6. Webhook ingestion
|
||||||
|
7. Return-mail / undeliverable mapping
|
||||||
|
8. Delivered-letter mapping, product-dependent
|
||||||
|
9. Rate-limit/send-limit handling
|
||||||
|
10. Sandbox test harness
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. Provider-Specific Assessment: DPAG / E-POSTBUSINESS
|
||||||
|
|
||||||
|
## 9.1 DPAG Profile
|
||||||
|
|
||||||
|
DPAG / E-POSTBUSINESS appears best modeled as a **postal-infrastructure-native hybrid-mail shipment API**.
|
||||||
|
|
||||||
|
The workflow centers on:
|
||||||
|
|
||||||
|
```text
|
||||||
|
PDF/PDF-A shipment upload
|
||||||
|
→ validation / positioning / cover-sheet handling
|
||||||
|
→ single or bulk submission
|
||||||
|
→ production data
|
||||||
|
→ shipment tracking
|
||||||
|
→ registered-mail / delivery-confirmation product evidence
|
||||||
|
```
|
||||||
|
|
||||||
|
The public Deutsche Post developer material explicitly describes single PDF documents, one-by-one and bulk upload, shipment processing information, bulk status requests, and tracking from uploading through delivery. Deutsche Post business API materials emphasize REST/Swagger, production data, shipment tracking, mass submission, address-window positioning aids, automatic positioning, individual cover sheets, and scheduled dispatch.
|
||||||
|
|
||||||
|
## 9.2 DPAG Strengths
|
||||||
|
|
||||||
|
* Direct connection to Deutsche Post hybrid-mail infrastructure.
|
||||||
|
* Strong postal-product alignment.
|
||||||
|
* Publicly documented PDF/PDF-A focus.
|
||||||
|
* Publicly documented bulk upload and bulk status.
|
||||||
|
* Publicly documented production data and shipment tracking.
|
||||||
|
* Publicly documented address-window positioning aids.
|
||||||
|
* Publicly documented automatic positioning and individual cover sheets.
|
||||||
|
* Publicly documented scheduled dispatch.
|
||||||
|
* Publicly referenced registered-letter use cases.
|
||||||
|
* Strong fit for German enterprise postal-delivery scenarios.
|
||||||
|
|
||||||
|
## 9.3 DPAG Weaknesses
|
||||||
|
|
||||||
|
* Adoption model appears more partner/business-software oriented.
|
||||||
|
* Exact active API access may require activation and credentials.
|
||||||
|
* Public material is less direct as a self-service developer experience than Pingen.
|
||||||
|
* Exact native status names and payloads need live API documentation.
|
||||||
|
* Exact idempotency behavior is unclear from public search result material.
|
||||||
|
* Exact webhook behavior is unclear from public search result material.
|
||||||
|
* Provider semantics may be more complex due to product diversity.
|
||||||
|
|
||||||
|
## 9.4 DPAG Opportunities
|
||||||
|
|
||||||
|
* Best candidate for postal-product completeness in the German market.
|
||||||
|
* Strong candidate for high-assurance physical dispatch scenarios.
|
||||||
|
* Registered-mail and shipment-tracking support can strengthen evidence models.
|
||||||
|
* Bulk upload/status can validate large-scale coordination cases.
|
||||||
|
* Address positioning and cover-sheet features can inform a powerful `print-layout-validation` subsystem.
|
||||||
|
* Scheduled dispatch can support deadline-aware coordination policies.
|
||||||
|
|
||||||
|
## 9.5 DPAG Threats / Risks
|
||||||
|
|
||||||
|
* Integration may be harder without partner activation or live account access.
|
||||||
|
* Coding agents may struggle if documentation is distributed across Swagger, PDFs, FAQs, and partner docs.
|
||||||
|
* Native status terminology may tempt overmapping to `delivery_confirmed`.
|
||||||
|
* Bulk status may be misread as per-recipient success unless child statuses are modeled.
|
||||||
|
* If idempotency is not native, duplicate physical shipment prevention must be adapter-managed.
|
||||||
|
* Product-specific registered-letter semantics must not be generalized.
|
||||||
|
|
||||||
|
## 9.6 DPAG Implementation Priority
|
||||||
|
|
||||||
|
Recommended implementation priority:
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Authentication / activation model
|
||||||
|
2. Single PDF/PDF-A shipment upload
|
||||||
|
3. Validation and PDF/PDF-A issue mapping
|
||||||
|
4. Status polling
|
||||||
|
5. Production data mapping
|
||||||
|
6. Postal handover mapping
|
||||||
|
7. Bulk upload and bulk status
|
||||||
|
8. Address positioning / automatic positioning metadata
|
||||||
|
9. Cover-sheet support
|
||||||
|
10. Scheduled dispatch support
|
||||||
|
11. Registered-mail / delivery-confirmation mapping
|
||||||
|
```
|
||||||
|
|
||||||
|
## 10. SWOT Summary Matrix
|
||||||
|
|
||||||
|
## 10.1 Binect SWOT
|
||||||
|
|
||||||
|
| Category | Assessment |
|
||||||
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| Strengths | Document-centric workflow, attachments, preview, validation, business-software fit, Swagger/API visibility. |
|
||||||
|
| Weaknesses | Less explicit public detail on webhooks, idempotency, return mail, registered/delivery-confirmation semantics. |
|
||||||
|
| Opportunities | Strong Binect-specific implementation candidate, document validation as differentiator, good fit for DMS/CRM dispatch. |
|
||||||
|
| Threats | Risk of status overinterpretation, duplicate-send risk if no native idempotency, polling complexity, account-specific capability uncertainty. |
|
||||||
|
|
||||||
|
## 10.2 Pingen SWOT
|
||||||
|
|
||||||
|
| Category | Assessment |
|
||||||
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| Strengths | Developer-friendly, SDKs, Idempotency-Key, rate limits, send limits, staging, Track & Trace, webhooks, return-mail processing. |
|
||||||
|
| Weaknesses | Exact delivered/return webhook semantics still require careful mapping; delivery confirmation is product-dependent. |
|
||||||
|
| Opportunities | Best external reference implementation, strong testability, strong coding-agent friendliness, good event-driven model. |
|
||||||
|
| Threats | Overinterpreting Track & Trace or delivered labels, relying too much on SDK abstraction, late return events changing assessments. |
|
||||||
|
|
||||||
|
## 10.3 DPAG SWOT
|
||||||
|
|
||||||
|
| Category | Assessment |
|
||||||
|
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| Strengths | Postal-infrastructure-native, PDF/PDF-A focus, bulk upload/status, production data, shipment tracking, address positioning, cover sheets, scheduled dispatch, registered-mail use cases. |
|
||||||
|
| Weaknesses | More partner/account activation complexity, less self-service developer digestability, exact webhook/idempotency details unclear publicly. |
|
||||||
|
| Opportunities | Strongest postal-product depth, excellent for German enterprise and high-assurance physical dispatch, bulk and registered-mail patterns. |
|
||||||
|
| Threats | Documentation fragmentation, product-specific complexity, risk of overmapping status, harder test setup without active account. |
|
||||||
|
|
||||||
|
## 11. Evidence Model Comparison
|
||||||
|
|
||||||
|
| Evidence stage | Binect | Pingen | DPAG |
|
||||||
|
| -------------------------------------- | ------------------------- | ------------------------------------- | ---------------------------------------------- |
|
||||||
|
| Digital upload accepted | Yes | Yes | Yes |
|
||||||
|
| Validation passed/failed | Strong public evidence | Strong public evidence | Strong public evidence |
|
||||||
|
| Preview/review | Publicly visible | Provider-specific / likely | Provider-specific |
|
||||||
|
| Submitted for sending | Yes | Yes | Yes |
|
||||||
|
| Production status | Status-dependent | Track & Trace-dependent | Publicly emphasized production data |
|
||||||
|
| Postal handover | Status-dependent | Sent-letter / Track & Trace semantics | Shipment tracking / status semantics |
|
||||||
|
| Ordinary delivery confirmation | Not generally assumed | Not generally assumed | Not generally assumed |
|
||||||
|
| Product-specific delivery confirmation | Provider/account-specific | Product-dependent | Product-dependent / registered products |
|
||||||
|
| Return/undeliverable evidence | Provider-specific | Strong public feature | Product/provider-specific |
|
||||||
|
| Address correction evidence | Provider-specific | Provider-specific | Premiumadress / product-specific possibilities |
|
||||||
|
|
||||||
|
## 12. Superset Baseline for hybridmail-connect
|
||||||
|
|
||||||
|
The provider comparison supports the following superset baseline:
|
||||||
|
|
||||||
|
```text
|
||||||
|
supports_document_upload
|
||||||
|
supports_validation
|
||||||
|
supports_address_validation
|
||||||
|
supports_address_position_validation
|
||||||
|
supports_restricted_area_validation
|
||||||
|
supports_pdf_or_pdfa_validation
|
||||||
|
supports_print_options
|
||||||
|
supports_shipping_options
|
||||||
|
supports_preview
|
||||||
|
supports_single_letter
|
||||||
|
supports_bulk_or_serial_letters
|
||||||
|
supports_send_submission
|
||||||
|
supports_status_polling
|
||||||
|
supports_webhooks
|
||||||
|
supports_track_and_trace
|
||||||
|
supports_production_status
|
||||||
|
supports_postal_handover_status
|
||||||
|
supports_registered_mail
|
||||||
|
supports_delivery_confirmation
|
||||||
|
supports_return_mail
|
||||||
|
supports_address_correction
|
||||||
|
supports_scheduled_dispatch
|
||||||
|
supports_cover_sheet
|
||||||
|
supports_idempotency
|
||||||
|
supports_staging
|
||||||
|
supports_rate_limits
|
||||||
|
supports_send_limits
|
||||||
|
```
|
||||||
|
|
||||||
|
No flavor supports all of these equally. Therefore every provider flavor must declare capabilities explicitly.
|
||||||
|
|
||||||
|
## 13. Recommended Provider Flavor Strategy
|
||||||
|
|
||||||
|
## 13.1 Use Pingen as External Developer-Experience Reference
|
||||||
|
|
||||||
|
Pingen is the cleanest reference for:
|
||||||
|
|
||||||
|
```text
|
||||||
|
idempotency
|
||||||
|
webhooks
|
||||||
|
Track & Trace
|
||||||
|
staging/sandbox
|
||||||
|
SDK examples
|
||||||
|
return-mail events
|
||||||
|
developer-facing onboarding
|
||||||
|
```
|
||||||
|
|
||||||
|
Pingen is likely the best provider to test the generic adapter event model from the outside because its public developer narrative is strongest.
|
||||||
|
|
||||||
|
## 13.2 Use Binect as Business-Document Workflow Reference
|
||||||
|
|
||||||
|
Binect is the best reference for:
|
||||||
|
|
||||||
|
```text
|
||||||
|
document upload
|
||||||
|
attachments
|
||||||
|
print/shipping options
|
||||||
|
preview
|
||||||
|
business-software integration
|
||||||
|
address/layout validation
|
||||||
|
```
|
||||||
|
|
||||||
|
Binect is strategically important if `coordination-engine` is intended to support Binect-related products or partner scenarios.
|
||||||
|
|
||||||
|
## 13.3 Use DPAG as Postal-Depth Reference
|
||||||
|
|
||||||
|
DPAG is the best reference for:
|
||||||
|
|
||||||
|
```text
|
||||||
|
postal-product richness
|
||||||
|
production data
|
||||||
|
shipment tracking
|
||||||
|
bulk upload/status
|
||||||
|
registered-mail variants
|
||||||
|
address positioning aids
|
||||||
|
automatic positioning
|
||||||
|
cover sheets
|
||||||
|
scheduled dispatch
|
||||||
|
German postal infrastructure alignment
|
||||||
|
```
|
||||||
|
|
||||||
|
DPAG is the strongest conceptual source for a complete German hybrid-mail standard, even if implementation may require more account and partner setup.
|
||||||
|
|
||||||
|
## 14. Implementation Complexity Assessment
|
||||||
|
|
||||||
|
| Provider | Implementation complexity | Reason |
|
||||||
|
| -------- | ------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| Pingen | Medium | Strong docs/SDKs/idempotency/webhooks reduce integration complexity, but status semantics still require careful evidence mapping. |
|
||||||
|
| Binect | Medium to High | Workflow is clear but exact status/webhook/idempotency semantics likely need live Swagger/API and domain knowledge. |
|
||||||
|
| DPAG | High | Rich product set, partner activation, PDF/PDF-A, positioning, production data, tracking, bulk status, and product-specific semantics increase complexity. |
|
||||||
|
|
||||||
|
## 15. Coding-Agent Friendliness
|
||||||
|
|
||||||
|
## 15.1 What Makes an API Coding-Agent Friendly?
|
||||||
|
|
||||||
|
An API is coding-agent friendly when a coding agent can reliably infer and implement correct behavior from its documentation without relying on undocumented assumptions.
|
||||||
|
|
||||||
|
Key properties:
|
||||||
|
|
||||||
|
```text
|
||||||
|
machine-readable OpenAPI schema
|
||||||
|
stable endpoint semantics
|
||||||
|
complete enum documentation
|
||||||
|
clear lifecycle diagrams
|
||||||
|
exact state machine definitions
|
||||||
|
idempotency semantics
|
||||||
|
webhook schemas
|
||||||
|
error-code catalog
|
||||||
|
retry rules
|
||||||
|
sandbox/test environment
|
||||||
|
sample requests and responses
|
||||||
|
SDKs
|
||||||
|
typed schemas
|
||||||
|
provider-specific glossary
|
||||||
|
status-to-business-meaning warnings
|
||||||
|
capability descriptor
|
||||||
|
contract tests
|
||||||
|
```
|
||||||
|
|
||||||
|
## 15.2 Coding-Agent Friendliness Comparison
|
||||||
|
|
||||||
|
| Dimension | Binect | Pingen | DPAG |
|
||||||
|
| ------------------------------------------------------ | ----------------------- | ---------------------- | ---------------------------------------- |
|
||||||
|
| Public developer positioning | Medium | High | Medium |
|
||||||
|
| Public Swagger/OpenAPI visibility | High | High / likely via docs | High |
|
||||||
|
| SDK availability | Not emphasized publicly | Strongly emphasized | Not primary public emphasis |
|
||||||
|
| Idempotency clarity | Unclear publicly | Strong | Unclear publicly |
|
||||||
|
| Webhook clarity | Unclear publicly | Strong | Unclear publicly |
|
||||||
|
| Sandbox/staging clarity | Unclear publicly | Strong | Present but activation/account-dependent |
|
||||||
|
| Status semantics digestability | Medium | Medium-High | Medium |
|
||||||
|
| Product semantics complexity | Medium | Medium | High |
|
||||||
|
| Agent implementation confidence from public docs alone | Medium | High | Medium-Low |
|
||||||
|
| Need for curated flavor spec | High | Medium | Very High |
|
||||||
|
|
||||||
|
## 15.3 Pingen Coding-Agent Friendliness
|
||||||
|
|
||||||
|
Pingen is most coding-agent friendly because it publicly emphasizes:
|
||||||
|
|
||||||
|
* SDKs
|
||||||
|
* code examples
|
||||||
|
* developer-friendly documentation
|
||||||
|
* Idempotency-Key support
|
||||||
|
* rate limits
|
||||||
|
* send limits
|
||||||
|
* staging/sandbox
|
||||||
|
* Track & Trace
|
||||||
|
* webhooks
|
||||||
|
|
||||||
|
These are exactly the affordances coding agents need to produce reliable integrations.
|
||||||
|
|
||||||
|
Remaining improvements would include:
|
||||||
|
|
||||||
|
```text
|
||||||
|
machine-readable event lifecycle schema
|
||||||
|
canonical webhook payload examples
|
||||||
|
explicit status-to-evidence mapping
|
||||||
|
clear statement of what "delivered" means per product
|
||||||
|
typed error-code catalog
|
||||||
|
contract-test suite
|
||||||
|
```
|
||||||
|
|
||||||
|
## 15.4 Binect Coding-Agent Friendliness
|
||||||
|
|
||||||
|
Binect has a public Swagger/API entry point and clearly relevant document workflow concepts. This is good for agents because the API is inspectable and operation-oriented.
|
||||||
|
|
||||||
|
However, coding-agent friendliness would improve significantly with:
|
||||||
|
|
||||||
|
```text
|
||||||
|
explicit OpenAPI examples for every endpoint
|
||||||
|
published status enum table
|
||||||
|
published validation issue enum table
|
||||||
|
published webhook contract if webhooks exist
|
||||||
|
published idempotency policy
|
||||||
|
provider status lifecycle diagram
|
||||||
|
duplicate-send prevention guide
|
||||||
|
preview and attachment examples
|
||||||
|
serial/child document examples
|
||||||
|
```
|
||||||
|
|
||||||
|
Binect’s public documentation is enough for a strong conceptual provider flavor, but a coding agent implementing the adapter would benefit from curated mapping files generated from the live Swagger.
|
||||||
|
|
||||||
|
## 15.5 DPAG Coding-Agent Friendliness
|
||||||
|
|
||||||
|
DPAG has strong conceptual and product depth, and public material confirms REST/Swagger documentation and many important capabilities. However, the integration model appears more partner/account-activation oriented, and the relevant knowledge is spread across developer pages, business API pages, PDFs, FAQs, partner docs, and possibly active-account Swagger.
|
||||||
|
|
||||||
|
Coding-agent friendliness would improve significantly with:
|
||||||
|
|
||||||
|
```text
|
||||||
|
single canonical OpenAPI bundle
|
||||||
|
machine-readable product capability matrix
|
||||||
|
complete status lifecycle map
|
||||||
|
PDF/PDF-A validation issue catalog
|
||||||
|
address-window positioning examples
|
||||||
|
automatic positioning examples
|
||||||
|
cover-sheet examples
|
||||||
|
bulk status examples
|
||||||
|
registered-mail event examples
|
||||||
|
delivery-confirmation semantics table
|
||||||
|
idempotency guidance
|
||||||
|
sandbox recipes
|
||||||
|
agent-readable "do not overclaim delivery" notes
|
||||||
|
```
|
||||||
|
|
||||||
|
DPAG is powerful but likely needs the most curation before coding agents can implement safely.
|
||||||
|
|
||||||
|
## 16. How API Digestability Could Be Improved
|
||||||
|
|
||||||
|
## 16.1 Provide Capability Descriptors
|
||||||
|
|
||||||
|
Every provider should expose a machine-readable capability descriptor.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
provider: pingen
|
||||||
|
supports:
|
||||||
|
webhooks: true
|
||||||
|
idempotency: true
|
||||||
|
return_mail: true
|
||||||
|
delivery_confirmation: product_dependent
|
||||||
|
registered_mail: true
|
||||||
|
preview: true
|
||||||
|
bulk: true
|
||||||
|
staging: true
|
||||||
|
```
|
||||||
|
|
||||||
|
This avoids agent guesswork and makes provider flavor selection automatable.
|
||||||
|
|
||||||
|
## 16.2 Publish Explicit Lifecycle State Machines
|
||||||
|
|
||||||
|
Provider documentation should include lifecycle diagrams with exact state names.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```text
|
||||||
|
created
|
||||||
|
→ uploaded
|
||||||
|
→ validation_pending
|
||||||
|
→ validation_passed
|
||||||
|
→ ready_for_sending
|
||||||
|
→ submitted
|
||||||
|
→ processing
|
||||||
|
→ handed_to_post
|
||||||
|
→ delivered | returned | unknown
|
||||||
|
```
|
||||||
|
|
||||||
|
Each state should declare:
|
||||||
|
|
||||||
|
```text
|
||||||
|
meaning
|
||||||
|
terminal or non-terminal
|
||||||
|
retry behavior
|
||||||
|
whether it implies postal handover
|
||||||
|
whether it implies delivery confirmation
|
||||||
|
whether it is product-dependent
|
||||||
|
```
|
||||||
|
|
||||||
|
## 16.3 Separate Production, Postal Handover, and Delivery Confirmation
|
||||||
|
|
||||||
|
Hybrid-mail APIs should explicitly separate:
|
||||||
|
|
||||||
|
```text
|
||||||
|
production_completed
|
||||||
|
postal_handover
|
||||||
|
postal_in_transit
|
||||||
|
delivery_confirmed
|
||||||
|
return_received
|
||||||
|
```
|
||||||
|
|
||||||
|
This is essential for coordination-engine because these states have different evidence grades.
|
||||||
|
|
||||||
|
## 16.4 Provide Status-to-Evidence Warnings
|
||||||
|
|
||||||
|
Each provider should document warnings such as:
|
||||||
|
|
||||||
|
```text
|
||||||
|
"sent" means the letter entered the sending process, not that the recipient received it.
|
||||||
|
"handed over" means the postal carrier accepted the letter, not that the recipient read it.
|
||||||
|
"delivered" is only available for selected products and does not imply human awareness.
|
||||||
|
```
|
||||||
|
|
||||||
|
These warnings are critical for safe automation.
|
||||||
|
|
||||||
|
## 16.5 Publish Webhook Schemas and Examples
|
||||||
|
|
||||||
|
Webhook documentation should include:
|
||||||
|
|
||||||
|
```text
|
||||||
|
event name
|
||||||
|
payload schema
|
||||||
|
example payload
|
||||||
|
retry behavior
|
||||||
|
signature verification
|
||||||
|
idempotency/deduplication key
|
||||||
|
event ordering assumptions
|
||||||
|
late event behavior
|
||||||
|
test-event endpoint
|
||||||
|
```
|
||||||
|
|
||||||
|
Pingen appears strongest here in public positioning, but all providers would benefit from standardized webhook docs.
|
||||||
|
|
||||||
|
## 16.6 Provide Idempotency Semantics
|
||||||
|
|
||||||
|
For hybrid mail, idempotency is not a convenience. It is a safety requirement.
|
||||||
|
|
||||||
|
Every provider should document:
|
||||||
|
|
||||||
|
```text
|
||||||
|
which endpoints support idempotency keys
|
||||||
|
how long keys are retained
|
||||||
|
what constitutes a conflict
|
||||||
|
what happens after timeout
|
||||||
|
how duplicate sends are prevented
|
||||||
|
whether idempotency covers upload, send, or both
|
||||||
|
```
|
||||||
|
|
||||||
|
If provider-native idempotency is unavailable, adapter-managed idempotency must compensate.
|
||||||
|
|
||||||
|
## 16.7 Provide Validation Issue Catalogs
|
||||||
|
|
||||||
|
Validation errors should be machine-readable.
|
||||||
|
|
||||||
|
Useful fields:
|
||||||
|
|
||||||
|
```text
|
||||||
|
issue_code
|
||||||
|
severity
|
||||||
|
category
|
||||||
|
page_number
|
||||||
|
bounding_box
|
||||||
|
fixable
|
||||||
|
human_message
|
||||||
|
machine_recommendation
|
||||||
|
```
|
||||||
|
|
||||||
|
This would greatly improve automated correction workflows.
|
||||||
|
|
||||||
|
## 16.8 Provide Sandbox and Golden Test Cases
|
||||||
|
|
||||||
|
Coding agents need reproducible fixtures.
|
||||||
|
|
||||||
|
Recommended test fixtures:
|
||||||
|
|
||||||
|
```text
|
||||||
|
valid one-page domestic letter
|
||||||
|
valid multi-page duplex letter
|
||||||
|
invalid address position
|
||||||
|
restricted-area violation
|
||||||
|
invalid PDF
|
||||||
|
PDF/A issue
|
||||||
|
unsupported country
|
||||||
|
return-mail simulation
|
||||||
|
registered-mail delivered simulation
|
||||||
|
bulk partial-failure simulation
|
||||||
|
duplicate idempotency simulation
|
||||||
|
```
|
||||||
|
|
||||||
|
These would make adapter implementation much safer.
|
||||||
|
|
||||||
|
## 16.9 Provide OpenAPI Files Optimized for Code Generation
|
||||||
|
|
||||||
|
Provider OpenAPI documents should be:
|
||||||
|
|
||||||
|
```text
|
||||||
|
complete
|
||||||
|
versioned
|
||||||
|
downloadable
|
||||||
|
validated
|
||||||
|
example-rich
|
||||||
|
schema-rich
|
||||||
|
enum-rich
|
||||||
|
error-rich
|
||||||
|
webhook-inclusive
|
||||||
|
security-scheme-explicit
|
||||||
|
```
|
||||||
|
|
||||||
|
A public Swagger UI is helpful, but agents benefit more from a downloadable OpenAPI file plus examples and contract tests.
|
||||||
|
|
||||||
|
## 17. Recommended Agent-Readable Provider Profile Format
|
||||||
|
|
||||||
|
Each provider flavor should maintain an agent-readable profile file.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
provider: pingen
|
||||||
|
flavor_version: 1.0
|
||||||
|
contract_version: 1.0
|
||||||
|
confidence: public_docs_plus_live_api_required
|
||||||
|
capabilities:
|
||||||
|
idempotency: true
|
||||||
|
webhooks: true
|
||||||
|
track_and_trace: true
|
||||||
|
return_mail: true
|
||||||
|
delivery_confirmation: product_dependent
|
||||||
|
status_mapping:
|
||||||
|
sent:
|
||||||
|
normalized_event: delivery.postal.handed_over
|
||||||
|
confidence: medium
|
||||||
|
warning: "Verify native semantics before enabling this mapping."
|
||||||
|
delivered:
|
||||||
|
normalized_event: delivery.postal.delivery_confirmed
|
||||||
|
confidence: product_dependent
|
||||||
|
warning: "Only for delivery-confirmation-capable product."
|
||||||
|
required_tests:
|
||||||
|
- duplicate_send_prevention
|
||||||
|
- validation_failure_mapping
|
||||||
|
- return_mail_late_event
|
||||||
|
- delivered_event_product_semantics
|
||||||
|
```
|
||||||
|
|
||||||
|
This would allow coding agents to implement providers without repeatedly re-reading large documents.
|
||||||
|
|
||||||
|
## 18. Recommended Implementation Order
|
||||||
|
|
||||||
|
## 18.1 For Proving the Generic Adapter
|
||||||
|
|
||||||
|
Use Pingen first if external provider access is easy.
|
||||||
|
|
||||||
|
Reason:
|
||||||
|
|
||||||
|
```text
|
||||||
|
idempotency + webhooks + Track & Trace + staging + SDKs
|
||||||
|
```
|
||||||
|
|
||||||
|
make it a strong proving ground.
|
||||||
|
|
||||||
|
## 18.2 For Binect Strategic Fit
|
||||||
|
|
||||||
|
Use Binect first if the immediate business case is Binect-owned or Binect-integrated.
|
||||||
|
|
||||||
|
Reason:
|
||||||
|
|
||||||
|
```text
|
||||||
|
document upload + attachments + preview + validation + business-letter dispatch
|
||||||
|
```
|
||||||
|
|
||||||
|
aligns strongly with Binect scenarios.
|
||||||
|
|
||||||
|
## 18.3 For Postal Completeness
|
||||||
|
|
||||||
|
Use DPAG early for conceptual completeness, but probably not as the first implementation unless account access and documentation are ready.
|
||||||
|
|
||||||
|
Reason:
|
||||||
|
|
||||||
|
```text
|
||||||
|
product richness + bulk + production data + tracking + registered mail
|
||||||
|
```
|
||||||
|
|
||||||
|
make it strategically important but implementation-heavy.
|
||||||
|
|
||||||
|
## 19. Provider Flavor Risk Controls
|
||||||
|
|
||||||
|
Each provider flavor MUST include the following safety controls:
|
||||||
|
|
||||||
|
```text
|
||||||
|
adapter-managed idempotency, even if provider idempotency exists
|
||||||
|
raw status preservation
|
||||||
|
conservative event mapping
|
||||||
|
product-specific delivery-confirmation mapping
|
||||||
|
batch child-status mapping
|
||||||
|
late return-event handling
|
||||||
|
explicit evidence grading
|
||||||
|
duplicate physical-send prevention
|
||||||
|
manual override support
|
||||||
|
provider capability descriptor
|
||||||
|
```
|
||||||
|
|
||||||
|
## 20. Recommended Hybrid-Mail Provider Abstraction
|
||||||
|
|
||||||
|
The comparison supports this provider abstraction:
|
||||||
|
|
||||||
|
```text
|
||||||
|
HybridmailProviderFlavor
|
||||||
|
capabilities
|
||||||
|
document_model
|
||||||
|
validation_model
|
||||||
|
option_model
|
||||||
|
send_model
|
||||||
|
status_model
|
||||||
|
tracking_model
|
||||||
|
return_model
|
||||||
|
delivery_confirmation_model
|
||||||
|
evidence_mapping
|
||||||
|
idempotency_model
|
||||||
|
testing_model
|
||||||
|
```
|
||||||
|
|
||||||
|
This should become the internal structure of each provider flavor implementation.
|
||||||
|
|
||||||
|
## 21. Summary
|
||||||
|
|
||||||
|
Binect, Pingen, and DPAG all fit the `hybridmail-connect` model, but each contributes a different design center:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Binect = document workflow depth
|
||||||
|
Pingen = developer/API friendliness
|
||||||
|
DPAG = postal-product and infrastructure depth
|
||||||
|
```
|
||||||
|
|
||||||
|
For the framework, this is good news. The three providers collectively validate the need for a generic hybrid-mail adapter model with provider-specific flavors.
|
||||||
|
|
||||||
|
The most important implementation principle is:
|
||||||
|
|
||||||
|
> Preserve provider-specific status detail, map conservatively to normalized evidence, and never turn physical dispatch terminology into coordination success without explicit product and policy support.
|
||||||
|
|
||||||
|
The most important improvement for coding-agent friendliness is:
|
||||||
|
|
||||||
|
> Publish machine-readable capability descriptors, lifecycle state machines, status/evidence mapping tables, webhook schemas, validation catalogs, idempotency semantics, and golden test fixtures.
|
||||||
|
|
||||||
2076
spec/HybridmailAdapterSpecification.md
Normal file
2076
spec/HybridmailAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1057
spec/HybridmailBinectSpecification.md
Normal file
1057
spec/HybridmailBinectSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1220
spec/HybridmailEpostbusinessSpecification.md
Normal file
1220
spec/HybridmailEpostbusinessSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1165
spec/HybridmailPingenSpecification.md
Normal file
1165
spec/HybridmailPingenSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
987
spec/ProductRequirementsDocument.md
Normal file
987
spec/ProductRequirementsDocument.md
Normal file
@@ -0,0 +1,987 @@
|
|||||||
|
# Product Requirements Document: coordination-engine
|
||||||
|
|
||||||
|
## 1. Product Name
|
||||||
|
|
||||||
|
**coordination-engine**
|
||||||
|
|
||||||
|
## 2. Product Intent
|
||||||
|
|
||||||
|
**coordination-engine** is a generalized framework for digital coordination as goal- and result-driven communication between multiple interacting parties. It enables the easy generation of scenario-specific communication applications by selecting only the relevant concepts from the framework to establish well-defined, headless communication applications.
|
||||||
|
|
||||||
|
The product implements the broader **coordination-framework** through a runtime **coordination-controller**, supporting reusable controllers for results, participants, payloads, access, notifications, deliveries, interactions, evidence, policy, and adapters.
|
||||||
|
|
||||||
|
## 3. Executive Summary
|
||||||
|
|
||||||
|
Digital communication should not be modeled primarily as the transport of messages from sender to receiver. In many modern scenarios, the more efficient and powerful model is to control access to payloads, action surfaces, and interaction flows while collecting evidence that the relevant parties became aware, accessed, acted, accepted, signed, paid, responded, or otherwise changed state.
|
||||||
|
|
||||||
|
**coordination-engine** provides a headless coordination runtime for building such systems. It treats communication as a goal-directed coordination process involving participants, payloads, notifications, deliveries, access rights, interaction events, policies, deadlines, and intended results.
|
||||||
|
|
||||||
|
Instead of asking only whether a message was sent or delivered, coordination-engine asks:
|
||||||
|
|
||||||
|
* What result is the initiator trying to achieve?
|
||||||
|
* Which participants are involved?
|
||||||
|
* Which payloads, notifications, deliveries, and interactions are required?
|
||||||
|
* What evidence is sufficient to mark progress or completion?
|
||||||
|
* Which follow-up actions are required under uncertainty?
|
||||||
|
* When is the coordination case successful, failed, partial, expired, or escalated?
|
||||||
|
|
||||||
|
The engine is intended to support many concrete applications, including digital postal delivery, document distribution, data collection, AGB acceptance, contract signing, invoice/payment collection, incident acknowledgement, approval workflows, onboarding, and regulated communication scenarios.
|
||||||
|
|
||||||
|
## 4. Problem Statement
|
||||||
|
|
||||||
|
Many digital communication systems are built around channels: email, SMS, push notifications, portals, messaging systems, file transfer, signature tools, payment systems, or CRM workflows. This leads to fragmented logic, duplicated business rules, weak evidence handling, and poor traceability.
|
||||||
|
|
||||||
|
Traditional message-delivery thinking is insufficient for digital coordination because:
|
||||||
|
|
||||||
|
1. **Sending is not success.** A message may be technically sent but never seen, understood, acted upon, or sufficient for the intended business result.
|
||||||
|
2. **Delivery is often access-based.** Digital payloads are often not transported to recipients but made available through controlled access.
|
||||||
|
3. **Multiple parties may interact.** Coordination can involve initiators, recipients, delegates, signers, payers, approvers, agents, systems, and intermediaries.
|
||||||
|
4. **Evidence matters.** Business outcomes require evidence of awareness, access, identity, authority, interaction, acceptance, payment, signature, or completion.
|
||||||
|
5. **Uncertainty is normal.** Many events produce only weak or ambiguous evidence, especially across channels like email.
|
||||||
|
6. **Follow-up must be policy-driven.** Reminders, escalation, fallback channels, revocation, retries, deadline handling, and manual review should be derived from explicit policies.
|
||||||
|
7. **Scenarios differ, but patterns repeat.** Digital postal delivery, contract signing, payment collection, and document collection use different adapters but similar coordination logic.
|
||||||
|
|
||||||
|
coordination-engine addresses this by providing a reusable framework for result-oriented digital coordination.
|
||||||
|
|
||||||
|
## 5. Product Vision
|
||||||
|
|
||||||
|
coordination-engine should become a headless coordination runtime that allows developers, operators, and product teams to define and run scenario-specific coordination applications by composing reusable concepts instead of hardcoding channel-specific workflows.
|
||||||
|
|
||||||
|
The long-term vision is:
|
||||||
|
|
||||||
|
> Define the intended result, participants, payloads, required evidence, policies, and adapters — and let the coordination engine orchestrate the process until the result is achieved, failed, expired, escalated, or manually closed.
|
||||||
|
|
||||||
|
## 6. Core Product Principle
|
||||||
|
|
||||||
|
**A coordination case is successful when its intended result is satisfied, not when messages have merely been sent.**
|
||||||
|
|
||||||
|
Digital coordination is the controlled arrangement of participants, payloads, access, notifications, deliveries, interactions, and evidence so that intended results can be achieved under uncertainty.
|
||||||
|
|
||||||
|
## 7. Target Users
|
||||||
|
|
||||||
|
### 7.1 Primary Users
|
||||||
|
|
||||||
|
#### Application Developers
|
||||||
|
|
||||||
|
Developers who need to build scenario-specific communication and coordination applications without reinventing delivery tracking, notification logic, evidence handling, and follow-up workflows.
|
||||||
|
|
||||||
|
#### Product Teams
|
||||||
|
|
||||||
|
Teams designing applications for document delivery, onboarding, contract closure, acceptance workflows, customer communication, payment collection, or compliance communication.
|
||||||
|
|
||||||
|
#### Operations Teams
|
||||||
|
|
||||||
|
Teams responsible for monitoring ongoing coordination cases, identifying unresolved participants, triggering manual follow-up, and reviewing evidence.
|
||||||
|
|
||||||
|
#### Automation Agents
|
||||||
|
|
||||||
|
Software agents that create, inspect, update, or close coordination cases through APIs or event streams.
|
||||||
|
|
||||||
|
### 7.2 Secondary Users
|
||||||
|
|
||||||
|
#### Compliance and Legal Stakeholders
|
||||||
|
|
||||||
|
Stakeholders who need auditable evidence of notification, delivery, acceptance, signature, payment, or response.
|
||||||
|
|
||||||
|
#### Business Analysts
|
||||||
|
|
||||||
|
Analysts who define coordination scenarios, result predicates, thresholds, deadlines, and follow-up policies.
|
||||||
|
|
||||||
|
#### Integration Partners
|
||||||
|
|
||||||
|
Teams integrating email, SMS, push, payment, signature, identity, storage, CRM, ERP, portal, or messaging systems.
|
||||||
|
|
||||||
|
## 8. Key Use Cases
|
||||||
|
|
||||||
|
### 8.1 Digital Postal Delivery
|
||||||
|
|
||||||
|
An initiator makes a PDF letter available to recipients through a portal. The system notifies recipients through email or other channels, observes access, records download/view evidence, and escalates unresolved cases.
|
||||||
|
|
||||||
|
### 8.2 Document Distribution
|
||||||
|
|
||||||
|
A company distributes a policy update, security notice, product change notice, or customer document to many recipients and wants to maximize access or acknowledgement within a defined timeframe.
|
||||||
|
|
||||||
|
### 8.3 Data and Document Collection
|
||||||
|
|
||||||
|
An initiator requests documents, forms, confirmations, or structured data from participants. The engine tracks notifications, access to the request, submissions, validation results, correction loops, and completion.
|
||||||
|
|
||||||
|
### 8.4 AGB / Terms Acceptance
|
||||||
|
|
||||||
|
A company publishes new terms and requires affected users or customers to review and accept them before a deadline. The engine tracks awareness, access, versioned payloads, authenticated acceptance, decline, and enforcement state.
|
||||||
|
|
||||||
|
### 8.5 Contract Signing
|
||||||
|
|
||||||
|
The system coordinates contract delivery, signer notification, access control, identity verification, signing, counter-signing, decline, expiry, and archival of final evidence.
|
||||||
|
|
||||||
|
### 8.6 Payment Collection
|
||||||
|
|
||||||
|
The system coordinates invoice availability, payment requests, notifications, payment links, payment attempts, successful settlement, failed payments, reminders, disputes, dunning escalation, and closure.
|
||||||
|
|
||||||
|
### 8.7 Incident Acknowledgement
|
||||||
|
|
||||||
|
The system sends urgent alerts, requires acknowledgements from relevant parties, escalates through multiple channels, and records time-to-awareness and response evidence.
|
||||||
|
|
||||||
|
### 8.8 Approval Workflow
|
||||||
|
|
||||||
|
The system coordinates one or more approvers around a payload, tracks access, review, approval, rejection, delegation, timeout, and escalation.
|
||||||
|
|
||||||
|
## 9. Scope
|
||||||
|
|
||||||
|
### 9.1 In Scope
|
||||||
|
|
||||||
|
coordination-engine shall provide:
|
||||||
|
|
||||||
|
* A generic model for coordination cases.
|
||||||
|
* A runtime coordination-controller.
|
||||||
|
* Participants, roles, endpoints, and participant states.
|
||||||
|
* Intended result definitions.
|
||||||
|
* Result evaluation and progress assessment.
|
||||||
|
* Payload/resource modeling.
|
||||||
|
* Access grants and access state tracking.
|
||||||
|
* Notification attempts and notification evidence.
|
||||||
|
* Delivery cases and delivery evidence.
|
||||||
|
* Interaction events and interaction state tracking.
|
||||||
|
* Evidence ledger with normalized events.
|
||||||
|
* Policy engine for follow-up decisions.
|
||||||
|
* Adapter interface for external systems.
|
||||||
|
* Scenario templates or patterns.
|
||||||
|
* Headless API for creating and managing coordination applications.
|
||||||
|
* Event-driven integration model.
|
||||||
|
* Audit trail for decisions and evidence.
|
||||||
|
* MVP support for at least one concrete scenario.
|
||||||
|
|
||||||
|
### 9.2 Out of Scope for MVP
|
||||||
|
|
||||||
|
The MVP does not need to provide:
|
||||||
|
|
||||||
|
* A full user interface.
|
||||||
|
* A complete no-code workflow builder.
|
||||||
|
* Built-in support for every communication channel.
|
||||||
|
* Legal validity guarantees for signatures, notices, or contracts.
|
||||||
|
* Full BPMN compatibility.
|
||||||
|
* Full CRM, ERP, payment, or document management implementation.
|
||||||
|
* Native long-term archive implementation.
|
||||||
|
* AI-based policy optimization.
|
||||||
|
* Complex multi-party negotiation logic.
|
||||||
|
|
||||||
|
These may be added later through adapters, scenario modules, or higher-level applications.
|
||||||
|
|
||||||
|
## 10. Conceptual Model
|
||||||
|
|
||||||
|
### 10.1 CoordinationCase
|
||||||
|
|
||||||
|
A **CoordinationCase** is the main runtime object. It represents a goal-directed coordination process initiated by one party to achieve an intended result involving one or more participants.
|
||||||
|
|
||||||
|
Core fields:
|
||||||
|
|
||||||
|
* `id`
|
||||||
|
* `initiator`
|
||||||
|
* `purpose`
|
||||||
|
* `scenario_type`
|
||||||
|
* `intended_result`
|
||||||
|
* `participants`
|
||||||
|
* `payloads`
|
||||||
|
* `action_surfaces`
|
||||||
|
* `access_grants`
|
||||||
|
* `notifications`
|
||||||
|
* `deliveries`
|
||||||
|
* `interactions`
|
||||||
|
* `evidence_events`
|
||||||
|
* `policies`
|
||||||
|
* `deadlines`
|
||||||
|
* `assessment`
|
||||||
|
* `next_actions`
|
||||||
|
* `closure_state`
|
||||||
|
|
||||||
|
### 10.2 Participant
|
||||||
|
|
||||||
|
A **Participant** is an actor involved in the coordination case.
|
||||||
|
|
||||||
|
Participants may be:
|
||||||
|
|
||||||
|
* Initiators
|
||||||
|
* Recipients
|
||||||
|
* Respondents
|
||||||
|
* Signers
|
||||||
|
* Payers
|
||||||
|
* Approvers
|
||||||
|
* Delegates
|
||||||
|
* Agents
|
||||||
|
* Organizations
|
||||||
|
* Systems
|
||||||
|
* Intermediaries
|
||||||
|
|
||||||
|
Each participant may have:
|
||||||
|
|
||||||
|
* Identity references
|
||||||
|
* Contact endpoints
|
||||||
|
* Roles
|
||||||
|
* Authority attributes
|
||||||
|
* Required outcomes
|
||||||
|
* Participant-specific state
|
||||||
|
* Participant-specific evidence level
|
||||||
|
* Next actions
|
||||||
|
|
||||||
|
### 10.3 IntendedResult
|
||||||
|
|
||||||
|
An **IntendedResult** defines what success means.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Payload accessed by all required recipients.
|
||||||
|
* Valid submissions received from all required respondents.
|
||||||
|
* Terms accepted by all active users.
|
||||||
|
* Contract signed by all required parties.
|
||||||
|
* Invoices paid above a defined amount threshold.
|
||||||
|
* Incident acknowledged by all critical participants.
|
||||||
|
|
||||||
|
An intended result should define:
|
||||||
|
|
||||||
|
* Result type
|
||||||
|
* Target population
|
||||||
|
* Required outcome
|
||||||
|
* Required evidence level
|
||||||
|
* Quantitative threshold
|
||||||
|
* Deadline
|
||||||
|
* Partial success rules
|
||||||
|
* Failure rules
|
||||||
|
* Fallback policy
|
||||||
|
|
||||||
|
### 10.4 Payload
|
||||||
|
|
||||||
|
A **Payload** is a meaningful resource involved in the coordination case.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* PDF letter
|
||||||
|
* Invoice
|
||||||
|
* Contract
|
||||||
|
* AGB version
|
||||||
|
* Form template
|
||||||
|
* Submitted document
|
||||||
|
* Payment request
|
||||||
|
* Signature envelope
|
||||||
|
* Receipt
|
||||||
|
* Structured data package
|
||||||
|
|
||||||
|
Payloads may have:
|
||||||
|
|
||||||
|
* Meaning
|
||||||
|
* Version
|
||||||
|
* Representation
|
||||||
|
* Instance
|
||||||
|
* Integrity hash
|
||||||
|
* Sensitivity
|
||||||
|
* Retention policy
|
||||||
|
* Access policy
|
||||||
|
* Validation rules
|
||||||
|
|
||||||
|
### 10.5 ActionSurface
|
||||||
|
|
||||||
|
An **ActionSurface** is the digital or physical place where a participant can interact with a payload or perform a required action.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Portal page
|
||||||
|
* Mobile app screen
|
||||||
|
* Payment page
|
||||||
|
* Signature flow
|
||||||
|
* Upload form
|
||||||
|
* Approval screen
|
||||||
|
* Chatbot flow
|
||||||
|
* API endpoint
|
||||||
|
* Email reply parser
|
||||||
|
* XMPP bot
|
||||||
|
* Social media direct message flow
|
||||||
|
|
||||||
|
### 10.6 Notification
|
||||||
|
|
||||||
|
A **Notification** is an awareness-oriented signal.
|
||||||
|
|
||||||
|
Its purpose is to create awareness or prompt attention. Notification is not delivery of the primary payload, although it may contain a small inline payload.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Email notification
|
||||||
|
* SMS reminder
|
||||||
|
* Push message
|
||||||
|
* XMPP message
|
||||||
|
* RSS item
|
||||||
|
* In-app notification
|
||||||
|
* Social media direct message
|
||||||
|
* Webhook event
|
||||||
|
|
||||||
|
### 10.7 Delivery
|
||||||
|
|
||||||
|
A **Delivery** is the controlled availability, access, transfer, retrieval, submission, or consumption of a payload.
|
||||||
|
|
||||||
|
Delivery may be:
|
||||||
|
|
||||||
|
* Outbound: initiator to participant
|
||||||
|
* Inbound: participant to initiator
|
||||||
|
* Peer-to-peer: participant to participant
|
||||||
|
* System-to-system
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* PDF downloaded
|
||||||
|
* Contract viewed
|
||||||
|
* Form submitted
|
||||||
|
* Data package uploaded
|
||||||
|
* Payment confirmation received
|
||||||
|
* Signed document archived
|
||||||
|
* API payload consumed
|
||||||
|
|
||||||
|
### 10.8 Interaction
|
||||||
|
|
||||||
|
An **Interaction** is a meaningful action performed by a participant, system, agent, or intermediary on an action surface or payload.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* Page loaded
|
||||||
|
* Notification opened
|
||||||
|
* Link clicked
|
||||||
|
* Portal login started
|
||||||
|
* Authentication completed
|
||||||
|
* Document viewed
|
||||||
|
* PDF downloaded
|
||||||
|
* Form submitted
|
||||||
|
* Signature completed
|
||||||
|
* Payment initiated
|
||||||
|
* Payment settled
|
||||||
|
* Decline submitted
|
||||||
|
* Dispute opened
|
||||||
|
* Acknowledgement recorded
|
||||||
|
|
||||||
|
### 10.9 EvidenceEvent
|
||||||
|
|
||||||
|
An **EvidenceEvent** is a normalized observation recorded by the engine or an adapter.
|
||||||
|
|
||||||
|
Evidence events should record:
|
||||||
|
|
||||||
|
* Event type
|
||||||
|
* Timestamp
|
||||||
|
* Source adapter
|
||||||
|
* Participant reference
|
||||||
|
* Actor reference
|
||||||
|
* Payload reference
|
||||||
|
* Action surface reference
|
||||||
|
* Raw event reference
|
||||||
|
* Normalized meaning
|
||||||
|
* Confidence
|
||||||
|
* Evidence grade
|
||||||
|
* Correlation ID
|
||||||
|
|
||||||
|
### 10.10 Policy
|
||||||
|
|
||||||
|
A **Policy** defines how the engine should interpret evidence and decide follow-up actions.
|
||||||
|
|
||||||
|
Policies may define:
|
||||||
|
|
||||||
|
* Required evidence levels
|
||||||
|
* Deadlines
|
||||||
|
* Reminder intervals
|
||||||
|
* Channel escalation rules
|
||||||
|
* Retry rules
|
||||||
|
* Fallback rules
|
||||||
|
* Manual review triggers
|
||||||
|
* Closure rules
|
||||||
|
* Failure rules
|
||||||
|
* Partial success rules
|
||||||
|
* Risk thresholds
|
||||||
|
|
||||||
|
## 11. Controller Architecture
|
||||||
|
|
||||||
|
### 11.1 Coordination Controller
|
||||||
|
|
||||||
|
The coordination-controller is the main runtime component.
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Create and manage CoordinationCases.
|
||||||
|
* Track participant-level and case-level progress.
|
||||||
|
* Coordinate subordinate controllers.
|
||||||
|
* Maintain current assessment.
|
||||||
|
* Trigger policy evaluation.
|
||||||
|
* Request follow-up actions.
|
||||||
|
* Close, fail, expire, or escalate cases.
|
||||||
|
|
||||||
|
### 11.2 Result Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Evaluate whether the intended result has been satisfied.
|
||||||
|
* Track thresholds and deadlines.
|
||||||
|
* Determine participant-level completion.
|
||||||
|
* Determine case-level completion.
|
||||||
|
* Support partial, failed, expired, and manually overridden states.
|
||||||
|
|
||||||
|
### 11.3 Participant Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Manage participants and roles.
|
||||||
|
* Maintain participant-specific state.
|
||||||
|
* Link participants to endpoints, payloads, actions, and evidence.
|
||||||
|
* Support delegates, organizations, systems, and agents.
|
||||||
|
|
||||||
|
### 11.4 Payload Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Manage payload identity, versioning, representations, and integrity.
|
||||||
|
* Link payloads to intended results and participants.
|
||||||
|
* Support inbound and outbound payloads.
|
||||||
|
* Track payload availability, validation, and archival state.
|
||||||
|
|
||||||
|
### 11.5 Access Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Manage access grants.
|
||||||
|
* Control access to payloads and action surfaces.
|
||||||
|
* Track access attempts, use, expiry, denial, delegation, and revocation.
|
||||||
|
* Integrate with identity and authorization systems.
|
||||||
|
|
||||||
|
### 11.6 Notification Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Create awareness through one or more notification channels.
|
||||||
|
* Track notification attempts.
|
||||||
|
* Normalize notification evidence.
|
||||||
|
* Support reminders, channel switching, and escalation.
|
||||||
|
* Avoid treating weak technical delivery as strong awareness evidence.
|
||||||
|
|
||||||
|
### 11.7 Delivery Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Track payload delivery, retrieval, submission, or consumption.
|
||||||
|
* Record delivery-side evidence.
|
||||||
|
* Distinguish payload availability from payload access and payload completion.
|
||||||
|
* Feed delivery evidence into result and notification assessment.
|
||||||
|
|
||||||
|
### 11.8 Interaction Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Normalize meaningful participant interactions.
|
||||||
|
* Distinguish weak interaction, identity-bound interaction, and result-relevant interaction.
|
||||||
|
* Classify bot, proxy, scanner, anonymous, authenticated, delegated, and authorized interactions where possible.
|
||||||
|
|
||||||
|
### 11.9 Identity & Authority Controller
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Evaluate actor identity.
|
||||||
|
* Evaluate authority and delegation.
|
||||||
|
* Link interactions to valid participants.
|
||||||
|
* Provide evidence grades for identity and authority.
|
||||||
|
* Integrate with IAM, SSO, MFA, signature, and authorization systems.
|
||||||
|
|
||||||
|
### 11.10 Evidence Ledger
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Store normalized evidence events.
|
||||||
|
* Preserve raw event references.
|
||||||
|
* Support auditability and traceability.
|
||||||
|
* Support derived assessments.
|
||||||
|
* Allow reconstruction of why a case was marked successful, failed, partial, expired, or escalated.
|
||||||
|
|
||||||
|
### 11.11 Policy Engine
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Evaluate policies against current evidence and state.
|
||||||
|
* Determine next actions.
|
||||||
|
* Trigger notifications, reminders, retries, escalations, fallback channels, manual reviews, or closure.
|
||||||
|
* Support scenario-specific policies.
|
||||||
|
|
||||||
|
### 11.12 Adapter Layer
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
* Provide integration with external protocols, systems, and providers.
|
||||||
|
* Translate native events into normalized EvidenceEvents.
|
||||||
|
* Expose actions that can be invoked by the engine.
|
||||||
|
* Declare adapter capabilities, failure modes, evidence strength, identity strength, latency, and cost profile.
|
||||||
|
|
||||||
|
Example adapters:
|
||||||
|
|
||||||
|
* Email
|
||||||
|
* SMS
|
||||||
|
* Mobile push
|
||||||
|
* In-app notification
|
||||||
|
* Portal
|
||||||
|
* RSS/feed
|
||||||
|
* XMPP/chat
|
||||||
|
* Webhook/API
|
||||||
|
* Payment provider
|
||||||
|
* Signature provider
|
||||||
|
* Document storage
|
||||||
|
* Identity provider
|
||||||
|
* CRM
|
||||||
|
* ERP
|
||||||
|
* Archive system
|
||||||
|
|
||||||
|
## 12. Scenario Patterns
|
||||||
|
|
||||||
|
coordination-engine should support reusable scenario patterns.
|
||||||
|
|
||||||
|
### 12.1 Broadcast Access Pattern
|
||||||
|
|
||||||
|
Used for distributing payloads to many participants.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Publish payload.
|
||||||
|
2. Grant access.
|
||||||
|
3. Notify participants.
|
||||||
|
4. Observe access and interaction.
|
||||||
|
5. Remind non-accessors.
|
||||||
|
6. Escalate unresolved cases.
|
||||||
|
7. Close when result threshold is met.
|
||||||
|
|
||||||
|
### 12.2 Request / Collect Pattern
|
||||||
|
|
||||||
|
Used for collecting payloads or responses.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Publish request.
|
||||||
|
2. Notify participants.
|
||||||
|
3. Provide submission surface.
|
||||||
|
4. Validate inbound payloads.
|
||||||
|
5. Request corrections.
|
||||||
|
6. Close when required submissions are valid.
|
||||||
|
|
||||||
|
### 12.3 Consent / Acceptance Pattern
|
||||||
|
|
||||||
|
Used for AGBs, policy changes, and consent collection.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Publish canonical terms version.
|
||||||
|
2. Notify affected participants.
|
||||||
|
3. Require authenticated access.
|
||||||
|
4. Record accept, decline, or no-response.
|
||||||
|
5. Enforce deadline consequences.
|
||||||
|
6. Archive evidence.
|
||||||
|
|
||||||
|
### 12.4 Contract Closure Pattern
|
||||||
|
|
||||||
|
Used for multi-party agreements.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Publish contract draft.
|
||||||
|
2. Grant access to parties.
|
||||||
|
3. Verify signer identity and authority.
|
||||||
|
4. Collect signatures.
|
||||||
|
5. Counter-sign if needed.
|
||||||
|
6. Archive final signed payload.
|
||||||
|
7. Notify completion.
|
||||||
|
|
||||||
|
### 12.5 Payment Collection Pattern
|
||||||
|
|
||||||
|
Used for invoices, subscriptions, and dunning.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Publish invoice or payment request.
|
||||||
|
2. Notify payer.
|
||||||
|
3. Provide payment action surface.
|
||||||
|
4. Observe payment lifecycle.
|
||||||
|
5. Remind failed or overdue payers.
|
||||||
|
6. Escalate to dunning or manual handling.
|
||||||
|
7. Close when payment is settled.
|
||||||
|
|
||||||
|
### 12.6 Alert / Acknowledgement Pattern
|
||||||
|
|
||||||
|
Used for incidents or urgent notices.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. Send multi-channel alert.
|
||||||
|
2. Require acknowledgement.
|
||||||
|
3. Escalate until acknowledged or expired.
|
||||||
|
4. Record time-to-awareness and response evidence.
|
||||||
|
|
||||||
|
## 13. Functional Requirements
|
||||||
|
|
||||||
|
### 13.1 Coordination Case Management
|
||||||
|
|
||||||
|
The system shall allow clients to create, read, update, cancel, expire, and close CoordinationCases.
|
||||||
|
|
||||||
|
The system shall support case-level states:
|
||||||
|
|
||||||
|
* draft
|
||||||
|
* active
|
||||||
|
* paused
|
||||||
|
* partially_completed
|
||||||
|
* completed
|
||||||
|
* failed
|
||||||
|
* expired
|
||||||
|
* cancelled
|
||||||
|
* manually_closed
|
||||||
|
|
||||||
|
### 13.2 Participant Management
|
||||||
|
|
||||||
|
The system shall allow each case to define one or more participants.
|
||||||
|
|
||||||
|
The system shall support participant roles, endpoints, required outcomes, and participant-level state.
|
||||||
|
|
||||||
|
The system shall support participant-level closure independent of case-level closure.
|
||||||
|
|
||||||
|
### 13.3 Intended Result Definition
|
||||||
|
|
||||||
|
The system shall support structured intended result definitions.
|
||||||
|
|
||||||
|
The system shall support result predicates based on participant state, evidence level, payload state, interaction state, payment state, signature state, deadlines, and thresholds.
|
||||||
|
|
||||||
|
### 13.4 Payload Management
|
||||||
|
|
||||||
|
The system shall support payload references and metadata.
|
||||||
|
|
||||||
|
The system shall distinguish payload meaning, version, representation, and instance.
|
||||||
|
|
||||||
|
The system shall support integrity references such as hashes where required.
|
||||||
|
|
||||||
|
The system shall support inbound and outbound payloads.
|
||||||
|
|
||||||
|
### 13.5 Access Management
|
||||||
|
|
||||||
|
The system shall support access grants to participants.
|
||||||
|
|
||||||
|
The system shall support access states such as:
|
||||||
|
|
||||||
|
* not_granted
|
||||||
|
* granted
|
||||||
|
* used
|
||||||
|
* denied
|
||||||
|
* expired
|
||||||
|
* revoked
|
||||||
|
* delegated
|
||||||
|
* abused_or_suspicious
|
||||||
|
|
||||||
|
### 13.6 Notification Management
|
||||||
|
|
||||||
|
The system shall support notification attempts through adapters.
|
||||||
|
|
||||||
|
The system shall track notification states and evidence.
|
||||||
|
|
||||||
|
The system shall distinguish technical channel events from awareness evidence.
|
||||||
|
|
||||||
|
The system shall support reminders and escalation attempts.
|
||||||
|
|
||||||
|
### 13.7 Delivery Management
|
||||||
|
|
||||||
|
The system shall support delivery tracking for payload availability, retrieval, submission, consumption, validation, and completion.
|
||||||
|
|
||||||
|
The system shall allow delivery evidence to contribute to notification and result assessment.
|
||||||
|
|
||||||
|
### 13.8 Interaction Tracking
|
||||||
|
|
||||||
|
The system shall record and classify participant interactions.
|
||||||
|
|
||||||
|
The system shall distinguish:
|
||||||
|
|
||||||
|
* anonymous interaction
|
||||||
|
* proxy interaction
|
||||||
|
* scanner/bot interaction
|
||||||
|
* suspected participant interaction
|
||||||
|
* authenticated participant interaction
|
||||||
|
* authorized actor interaction
|
||||||
|
* result-relevant interaction
|
||||||
|
|
||||||
|
### 13.9 Evidence Ledger
|
||||||
|
|
||||||
|
The system shall maintain an append-only or audit-safe evidence ledger.
|
||||||
|
|
||||||
|
The system shall store normalized evidence events.
|
||||||
|
|
||||||
|
The system shall preserve raw event references when available.
|
||||||
|
|
||||||
|
The system shall support derived assessments without losing original observations.
|
||||||
|
|
||||||
|
### 13.10 Policy Evaluation
|
||||||
|
|
||||||
|
The system shall evaluate policies based on current case state and evidence.
|
||||||
|
|
||||||
|
The system shall generate next actions such as:
|
||||||
|
|
||||||
|
* wait
|
||||||
|
* notify
|
||||||
|
* remind
|
||||||
|
* retry
|
||||||
|
* escalate
|
||||||
|
* switch_channel
|
||||||
|
* request_correction
|
||||||
|
* revoke_access
|
||||||
|
* extend_deadline
|
||||||
|
* manual_review
|
||||||
|
* close_success
|
||||||
|
* close_failure
|
||||||
|
|
||||||
|
### 13.11 Adapter Interface
|
||||||
|
|
||||||
|
The system shall define a standard adapter interface.
|
||||||
|
|
||||||
|
Adapters shall declare:
|
||||||
|
|
||||||
|
* supported actions
|
||||||
|
* emitted events
|
||||||
|
* normalized event mappings
|
||||||
|
* evidence strength
|
||||||
|
* identity strength
|
||||||
|
* failure modes
|
||||||
|
* latency profile
|
||||||
|
* cost profile
|
||||||
|
|
||||||
|
### 13.12 API
|
||||||
|
|
||||||
|
The system shall expose a headless API for:
|
||||||
|
|
||||||
|
* Creating coordination cases
|
||||||
|
* Registering participants
|
||||||
|
* Registering payloads
|
||||||
|
* Creating access grants
|
||||||
|
* Triggering notifications
|
||||||
|
* Recording evidence events
|
||||||
|
* Querying assessments
|
||||||
|
* Fetching next actions
|
||||||
|
* Closing cases
|
||||||
|
* Registering adapters
|
||||||
|
* Defining scenario templates
|
||||||
|
|
||||||
|
## 14. Non-Functional Requirements
|
||||||
|
|
||||||
|
### 14.1 Headless First
|
||||||
|
|
||||||
|
coordination-engine shall be designed as a headless service with APIs and event interfaces. User interfaces shall be built as separate applications.
|
||||||
|
|
||||||
|
### 14.2 Scenario Composability
|
||||||
|
|
||||||
|
The system shall allow scenario-specific applications to select only the relevant concepts from the framework.
|
||||||
|
|
||||||
|
A simple notification scenario should not require contract-signing, payment, or document-validation concepts.
|
||||||
|
|
||||||
|
### 14.3 Auditability
|
||||||
|
|
||||||
|
The system shall support reconstruction of case decisions from evidence events, policies, and state transitions.
|
||||||
|
|
||||||
|
### 14.4 Extensibility
|
||||||
|
|
||||||
|
The system shall support new adapters, scenario patterns, result types, and evidence types without changing the core runtime.
|
||||||
|
|
||||||
|
### 14.5 Reliability
|
||||||
|
|
||||||
|
The system shall handle retries, idempotency, duplicate events, late events, and conflicting evidence.
|
||||||
|
|
||||||
|
### 14.6 Security
|
||||||
|
|
||||||
|
The system shall support secure handling of sensitive payload metadata, participant identifiers, access grants, and evidence.
|
||||||
|
|
||||||
|
### 14.7 Privacy
|
||||||
|
|
||||||
|
The system shall allow minimization of stored personal data and support references to external identity, document, or CRM systems.
|
||||||
|
|
||||||
|
### 14.8 Observability
|
||||||
|
|
||||||
|
The system shall expose operational metrics for case progress, unresolved participants, adapter failures, policy actions, escalation rates, and result satisfaction.
|
||||||
|
|
||||||
|
### 14.9 Portability
|
||||||
|
|
||||||
|
The framework shall not be coupled to one channel, provider, protocol, cloud, identity system, or document system.
|
||||||
|
|
||||||
|
### 14.10 Agent-Friendliness
|
||||||
|
|
||||||
|
The APIs, schemas, state models, and events shall be suitable for use by software agents and automation systems.
|
||||||
|
|
||||||
|
## 15. MVP Scope
|
||||||
|
|
||||||
|
The MVP should prove the core abstraction with one or two concrete scenario patterns.
|
||||||
|
|
||||||
|
### 15.1 MVP Candidate Scenario A: Digital Payload Notification and Access
|
||||||
|
|
||||||
|
The MVP shall support:
|
||||||
|
|
||||||
|
* Create a coordination case.
|
||||||
|
* Add participants.
|
||||||
|
* Register one outbound payload.
|
||||||
|
* Grant participant-specific access.
|
||||||
|
* Send or simulate notification attempts.
|
||||||
|
* Record notification evidence.
|
||||||
|
* Record access and payload interaction events.
|
||||||
|
* Evaluate participant-level state.
|
||||||
|
* Evaluate case-level result.
|
||||||
|
* Generate reminder or closure actions.
|
||||||
|
|
||||||
|
### 15.2 MVP Candidate Scenario B: Request / Collect
|
||||||
|
|
||||||
|
The MVP may additionally support:
|
||||||
|
|
||||||
|
* Publish a request for inbound payloads.
|
||||||
|
* Track participant submissions.
|
||||||
|
* Validate submitted payload status.
|
||||||
|
* Request corrections.
|
||||||
|
* Close participant state when valid submission is received.
|
||||||
|
|
||||||
|
### 15.3 MVP Required Controllers
|
||||||
|
|
||||||
|
The MVP shall include minimal versions of:
|
||||||
|
|
||||||
|
* Coordination Controller
|
||||||
|
* Result Controller
|
||||||
|
* Participant Controller
|
||||||
|
* Payload Controller
|
||||||
|
* Access Controller
|
||||||
|
* Notification Controller
|
||||||
|
* Interaction Controller
|
||||||
|
* Evidence Ledger
|
||||||
|
* Policy Engine
|
||||||
|
* Adapter Interface
|
||||||
|
|
||||||
|
### 15.4 MVP Adapters
|
||||||
|
|
||||||
|
The MVP may initially implement simulated adapters only.
|
||||||
|
|
||||||
|
Recommended first real adapters:
|
||||||
|
|
||||||
|
* Email adapter
|
||||||
|
* Portal/action-surface adapter
|
||||||
|
* Webhook adapter
|
||||||
|
|
||||||
|
### 15.5 MVP Success Criteria
|
||||||
|
|
||||||
|
The MVP is successful when a developer can define a simple scenario-specific coordination application without hardcoding the full workflow.
|
||||||
|
|
||||||
|
The MVP should demonstrate:
|
||||||
|
|
||||||
|
* A case with multiple participants.
|
||||||
|
* Participant-level progress.
|
||||||
|
* Evidence-driven state transitions.
|
||||||
|
* At least one ambiguous/undef state.
|
||||||
|
* At least one follow-up action generated by policy.
|
||||||
|
* At least one successful completion based on interaction or delivery evidence.
|
||||||
|
* Traceability from final assessment back to evidence events.
|
||||||
|
|
||||||
|
## 16. Initial Domain Vocabulary
|
||||||
|
|
||||||
|
### Coordination
|
||||||
|
|
||||||
|
The result-oriented orchestration of participants, payloads, access, actions, timing, evidence, and policies.
|
||||||
|
|
||||||
|
### Communication
|
||||||
|
|
||||||
|
The semantic exchange layer used to convey meaning, requests, instructions, context, and status.
|
||||||
|
|
||||||
|
### Notification
|
||||||
|
|
||||||
|
An awareness-oriented communication act.
|
||||||
|
|
||||||
|
### Delivery
|
||||||
|
|
||||||
|
The controlled availability, access, transfer, retrieval, submission, or consumption of a payload.
|
||||||
|
|
||||||
|
### Payload
|
||||||
|
|
||||||
|
The meaningful content, data, document, resource, action request, or artifact involved in a coordination case.
|
||||||
|
|
||||||
|
### ActionSurface
|
||||||
|
|
||||||
|
The interface or endpoint where participants can interact with the coordination case.
|
||||||
|
|
||||||
|
### Interaction
|
||||||
|
|
||||||
|
A meaningful action by a participant, system, agent, or intermediary.
|
||||||
|
|
||||||
|
### Evidence
|
||||||
|
|
||||||
|
An observed fact or signal used to assess progress, uncertainty, success, failure, or required follow-up.
|
||||||
|
|
||||||
|
### IntendedResult
|
||||||
|
|
||||||
|
The desired outcome the initiator wants to achieve.
|
||||||
|
|
||||||
|
### Policy
|
||||||
|
|
||||||
|
A set of rules that interprets evidence and determines next actions.
|
||||||
|
|
||||||
|
## 17. Open Questions
|
||||||
|
|
||||||
|
1. Should coordination-engine define its own DSL for intended results and policies, or start with JSON/YAML schemas plus application-side evaluation hooks?
|
||||||
|
2. Should evidence events be strictly append-only in the first version?
|
||||||
|
3. How much payload metadata should coordination-engine own versus reference externally?
|
||||||
|
4. Should access control be implemented internally or delegated to external IAM/portal systems in the MVP?
|
||||||
|
5. Should scenario templates be first-class runtime objects or code-level configuration?
|
||||||
|
6. How should conflicting evidence be represented?
|
||||||
|
7. Should participant identity and authority be modeled minimally in the MVP or deferred to adapter integrations?
|
||||||
|
8. What is the right boundary between coordination-engine and workflow engines such as BPMN systems?
|
||||||
|
9. Should the engine include built-in timers and scheduling, or emit next-action recommendations to an external scheduler?
|
||||||
|
10. What should be the first real scenario used to validate the framework?
|
||||||
|
|
||||||
|
## 18. Risks
|
||||||
|
|
||||||
|
### 18.1 Over-Abstraction
|
||||||
|
|
||||||
|
The framework may become too abstract to implement efficiently. Mitigation: validate with concrete scenario patterns early.
|
||||||
|
|
||||||
|
### 18.2 Workflow Engine Creep
|
||||||
|
|
||||||
|
The product may drift into becoming a generic workflow engine. Mitigation: keep the core focused on coordination cases, participants, payloads, evidence, and result satisfaction.
|
||||||
|
|
||||||
|
### 18.3 Adapter Complexity
|
||||||
|
|
||||||
|
Adapters may become large and provider-specific. Mitigation: separate adapter capability declarations from normalized evidence events.
|
||||||
|
|
||||||
|
### 18.4 Legal Misinterpretation
|
||||||
|
|
||||||
|
Users may assume the system provides legal proof by default. Mitigation: model evidence levels and avoid claiming legal validity unless provided by scenario-specific integrations and policies.
|
||||||
|
|
||||||
|
### 18.5 Privacy Risk
|
||||||
|
|
||||||
|
Evidence tracking can become invasive. Mitigation: support data minimization, external references, retention policies, and privacy-aware configuration.
|
||||||
|
|
||||||
|
### 18.6 Weak Evidence Misclassification
|
||||||
|
|
||||||
|
Weak events such as email opens or anonymous clicks may be misclassified as success. Mitigation: evidence grading and scenario-specific required evidence levels.
|
||||||
|
|
||||||
|
## 19. Acceptance Criteria
|
||||||
|
|
||||||
|
The first useful version of coordination-engine shall allow:
|
||||||
|
|
||||||
|
1. A client to create a CoordinationCase with an IntendedResult.
|
||||||
|
2. A client to add multiple participants.
|
||||||
|
3. A client to register payloads and access surfaces.
|
||||||
|
4. The engine to record normalized EvidenceEvents.
|
||||||
|
5. The engine to evaluate participant-level state.
|
||||||
|
6. The engine to evaluate case-level result state.
|
||||||
|
7. The engine to distinguish success, fail, partial, active, expired, and undef/uncertain states.
|
||||||
|
8. The engine to generate next actions from policy.
|
||||||
|
9. The engine to explain why a state or action was derived.
|
||||||
|
10. A scenario-specific application to use only a relevant subset of the framework.
|
||||||
|
11. At least one adapter or simulated adapter to emit evidence events.
|
||||||
|
12. At least one end-to-end scenario to close successfully based on interaction or delivery evidence.
|
||||||
|
|
||||||
|
## 20. Strategic Positioning
|
||||||
|
|
||||||
|
coordination-engine is not merely an email system, notification service, document delivery tracker, workflow engine, or campaign automation tool.
|
||||||
|
|
||||||
|
It is a generalized digital coordination runtime.
|
||||||
|
|
||||||
|
Its core value lies in combining:
|
||||||
|
|
||||||
|
* Result-driven coordination
|
||||||
|
* Multi-party participant state
|
||||||
|
* Controlled payload access
|
||||||
|
* Notification and delivery abstraction
|
||||||
|
* Interaction evidence
|
||||||
|
* Policy-driven follow-up
|
||||||
|
* Adapter-based extensibility
|
||||||
|
* Headless application generation
|
||||||
|
|
||||||
|
This makes it suitable as a foundational engine for building specialized communication and coordination applications across business, legal, operational, and technical domains.
|
||||||
|
|
||||||
1394
spec/RssAdapterSpecification.md
Normal file
1394
spec/RssAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1776
spec/RuntimeArchitectureAndAdapterSubsystem.md
Normal file
1776
spec/RuntimeArchitectureAndAdapterSubsystem.md
Normal file
File diff suppressed because it is too large
Load Diff
1699
spec/SmsAdapterSpecification.md
Normal file
1699
spec/SmsAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
1621
spec/XmppAdapterSpecification.md
Normal file
1621
spec/XmppAdapterSpecification.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user