← Back to directory

communication-and-integrations.md

architecture/communication-and-integrations.md · 20.3 KB · 2026-11-02 12:48

Communication and Integrations

Status: settled semantic contract, 2026-09-11; live backends are later implementation depth after the first bounded milestone. Owner: Communication and Integration reusable execution responsibilities, normalized backend tools, and external-operation boundaries. Examples are illustrative, not fixed protocol interfaces, delivery guarantees, or backend support commitments.

Canonical Prerequisites

Shared Model and Boundaries

Messages, notifications, templates, integration configurations, site references, tool definitions, delivery records, and addressable mappings use the universal model. Their types are themselves addressable; adapters do not establish isolated stores or bespoke foundational schemas. Platform objects and remote identities are related through explicit source mappings, not equated because their names match. Backend-specific payloads may be typed values or source material; they must not become the core workflow's independent data model. Credentials remain behind the operational trust boundary, with controlled references where needed rather than exposed secrets in reusable configuration. An engine is a reusable execution responsibility, not necessarily a separate service, module, or PHP class. Communication owns intentional messages and delivery context; Integration owns external capability discovery, mapping, and invocation. One operation can compose both, such as sending a templated email through an external provider.

An Action is the provider-independent semantic request; an Integration is the external system/service; a Business Connection is the configured relationship to a provider; and a Provider is the trusted adapter translating the Action request and typed result. A Capability Action must not encode provider-specific semantics. Provider credentials remain in the protected credential boundary and are never ordinary universally readable Object properties. The initial send_email implementation is a no-network simulation Provider only; live providers and asynchronous external execution are deferred. Its result explicitly distinguishes simulation from sending or delivery, and the stub has no network or credential access.

Communication Responsibility

Inputs include permitted recipients, purpose, content/template references, relevant business subjects, and channel/destination context. Actions include rendering a permitted template, requesting email/messaging/in-app delivery, and recording the communication's outcome. Outputs include addressable messages or notifications and inspectable delivery history linked to the initiating subject/action. Recipients, ownership, sender authority, and applicable preferences must be evaluated, not inferred from mere access to a contact address. Templates can reuse content and brand context without copying business identity into a separate mailing universe. Communication history should distinguish intended message, delivery attempt/result, and any observed recipient interaction. No universal claim about delivery receipt, reading, ordering, or exactly-once sending is made here. Invalid recipients, missing content, denied authority, unavailable destinations, and delivery failures must remain distinguishable. User-facing feedback should say what is known, including uncertainty about whether an external service accepted a message.

Admission Confirmation Communication

User registration (principal.register, a legacy identifier for the User registration Operation) requests one confirmation message addressed only to the newly registered normalized email identity. The message is a notification of an admission action, not an authentication channel: it contains a purpose-bound, expiring, single-use link or equivalent confirmation action and must not include a password, credential hash, reusable session token or generic login mechanism. The browser registration response must not expose the raw challenge merely because a delivery adapter is unavailable.

Communication records the intended message, template/version, recipient identity reference, delivery attempts and known result without storing the raw challenge in ordinary message content or logs. accepted, failed and unknown delivery outcomes remain distinct. A delivery failure does not activate the User or imply that confirmation is impossible; a controlled resend may issue a new challenge subject to admission rate limits. Confirmation itself remains the identity Operation and performs the authoritative single-use check. Provider retries must not consume a challenge more than once or create duplicate activation effects.

This communication is platform admission context rather than Business-scoped communication. Recipient authorization comes from the pending identity created by principal.register; it is not inferred from Business membership or contact access. The message should identify the purpose, expiry and safe destination, and should provide a non-secret route to request assistance or a replacement challenge. Provider configuration and delivery implementation remain separate from the identity contract.

Notifications Are Not Events

Notifications are user-facing communications about relevant activity, not the canonical Event itself. Examples include publication success/failure, approval requests, campaign alerts, and other operational exceptions. Delivery channels may include in-app, email, or webhook where supported and authorised. An event can lead to notifications; a notification can link to the event, action, subject, or approval request it concerns. Read/unread state and dismissing a notification must not rewrite the business event or constitute approval. An activity feed is a projection of relevant history; it is not automatically a complete audit trail or notification-delivery system. Preferences, prioritisation, notification flooding, and delivery failure need explicit product/runtime handling. Suppression or failed notification delivery must not be represented as absence of the underlying business occurrence.

Integration Responsibility

Inputs include authorised connection configuration, source/destination identity, a requested capability, validated arguments, and relevant context. Capabilities may include connection testing, discovery, tool retrieval, draft creation/revision, publication, deletion, and metrics retrieval. They may also include webhooks, synchronisation, import, and export; no connector is assumed to support every operation.

Every Business-scoped integration operation, including synchronisation, import, export, publication and webhook processing, must satisfy the canonical subscription entitlement gate in subscriptions and entitlements (intended future architecture; all Businesses are currently treated as active and no entitlement is enforced). This gate is an operational prerequisite and does not define ownership or revoke Business authority during suspension. An integration has no independent identity or authority: it operates under authority delegated by a User, and the technical adapter or worker is execution provenance only (see delegated authority for automation). Adapters translate between platform types and external API/authentication/content formats while preserving source mapping and result meaning. Outputs identify affected local/remote objects, actual operation results, limitations, and failures without leaking secrets. Incoming webhooks and imported values require source/authenticity, type, permission, and policy checks before causing platform effects. Import/export must preserve meaningful identity, relationships, and provenance rather than create an untraceable text dump or disconnected duplicate universe. Synchronisation conflicts, remote deletions, API version changes, deprecated endpoints, and stale discovery require explicit handling. Outbound formatting and validation reflect supported content types, character limits, media rules, nesting, and rate limits. An extension must declare capability scope and trust requirements; it must not receive arbitrary filesystem/database access by default. Plugin registration, packaging, worker support, and deployment remain implementation work, not infrastructure implied by an adapter name.

Dataset ingestion is distinct from a live integration. It may import a CSV, spreadsheet, CRM export, historical archive, analytics export or other structured source without requiring a permanent connection. Ingestion must identify the source and collection context, map the dataset to permitted platform Types and Relationships, validate values and references, surface ambiguity or rejected rows, and preserve imported provenance and authority standing. Successful import is not proof that every source claim is authoritative, and an imported dataset must not remain an untraceable attachment when its approved purpose is to contribute information to the Business model.

Live integration instead concerns an available external resource and its current connection, capabilities, remote identities and operation results. A dataset can later inform an integration or vice versa, but the two paths must not be conflated into a promise of synchronization, permanent connectivity or automatic external authority.

Normalized Backend Tool Contract

Core content, generation, review, and delivery use normalized Idiosyncrasy tool definitions rather than raw WordPress API shapes. Tools need stable platform identity, a human-readable purpose, accepted fields/attributes, constraints, style/brand context, valid examples, and backend source mapping. Definitions and their schemas are addressable universal objects; JSON Schema below illustrates typed validation data, not a second foundational model. The schema dialect, type identifiers, and field names below are examples, not a selected storage or execution API.

{
  "id": "tool:site-a:section-heading",
  "type": "type:content-tool",
  "value": {
    "title": "Section heading",
    "purpose": "Introduce a section with a site-supported heading",
    "inputSchema": {
      "type": "object",
      "required": ["text", "level"],
      "additionalProperties": false,
      "properties": {
        "text": { "type": "string", "minLength": 1, "maxLength": 120 },
        "level": { "type": "integer", "enum": [2, 3] },
        "children": { "type": "array", "maxItems": 0 }
      }
    },
    "styleContext": { "brand": "brand:acme", "typographyRole": "section-heading" },
    "examples": [{ "text": "Our services", "level": 2 }],
    "sourceMapping": {
      "site": "site:a",
      "backend": "wordpress",
      "resource": "core/heading",
      "discovery": "discovery:site-a:observed",
      "attributes": { "text": "content", "level": "level" }
    }
  }
}

Here type:content-tool denotes an addressable type definition; inputSchema is a nested value governed by that type. The 120-character limit, heading levels, and no-children constraint illustrate a curated tool, not universal WordPress restrictions. A valid invocation uses the permitted fields, for example {"text":"Our services","level":2} in the selected tool/site context. Invalid examples include level 9, an unknown script field, forbidden child content, or using Site A's tool against Site B without a valid mapping. Schema conformance is necessary but not sufficient: availability, platform relationships, destination authority, policy, and content safety must also pass. The adapter maps valid normalized content into the backend's markup/payload and interprets the result; the AI layer does not own that conversion contract.

Site Context, Fidelity, and Coverage

Tool sets are scoped to the connected site/source context; a block or pattern on one theme is not evidence of availability elsewhere. Coverage measures how much useful source functionality is recognised. Fidelity measures whether recognised tools accurately describe valid fields, structure, style, constraints, and usage. Prefer a smaller reliable tool set to a broad set of uncertain capabilities; flag or omit resources that cannot be reliably normalized. Source mapping must retain the site, resource identity, discovery provenance, and relevant style context needed to inspect the mapping. Discovery freshness and removed/changed tools matter when saved content refers to an earlier resource set. The implementation must distinguish discovery failure or unsupported resources from a successful discovery of an empty set. Discovered tool representations remain scoped, versioned and source-linked. Saved content retains the tool revision used; removed or incompatible tools require revalidation, never silent substitution. The WordPress mechanism specifies refresh and retirement for that optional adapter. Native content backends can implement the same conceptual boundary without mimicking WordPress storage or markup. Model pages, blocks, media, forms, redirects, and SEO coherently before selecting an editor or extension ecosystem.

Delivery and External Failures

Illustrative publishing flow: schedule -> job -> adapter -> API -> response -> recorded result; the first two steps belong to workflow/runtime design.

A simulated communication result is explicitly marked simulated and is not evidence of remote acceptance, sending, delivery or recipient interaction. The first send_email implementation is a provider-free trusted simulation handler: it makes no network request, has no local business-object mutation effects, and does not claim that an email was sent or delivered. It still uses the existing Operation -> Command -> Action Execution/Attempt/Outcome/Event/Provenance model; the Command has an empty business-effect list and the required evidence is persisted atomically. The semantic request binds the exact Operation identity/revision, validated inputs and resolved source references for fingerprinting and replay/conflict handling. Simulation evidence explicitly records simulation/not-sent state, network_attempted=false, sender-configured state and aggregate recipient/attachment counts. Persisted Command, Action Execution, Attempt and Outcome evidence does not contain recipient/sender addresses or message body content. This evidence proves invocation and its simulated result, not an external effect. Validate the effective content/variant, required fields, character limits, media, formatting, selected tools, and authorisation before delivery. Illustrative delivery labels include pending, publishing, published, and failed; they are not a fixed universal lifecycle or linear sequence. Content editorial state and remote delivery status are distinct; a successful draft creation is not live publication. Classify unavailable API, expired/revoked credentials, rate limiting, invalid payload, remote rejection, uncertain outcome, and partial success meaningfully. Multi-media publication may partially succeed; do not collapse that into success for the entire request. Transient versus permanent errors inform eligibility under the settled retry contract, but not every failure is safe to repeat. Use the Command/Action retry and recovery contract: stable semantic identity, explicit retained Attempts, deterministic safe-repeat keys and reconciliation before repeating unsafe or unknown effects. Concrete backoff/adapter lookup parameters implement that contract, not a new architecture decision. Retain useful request/response context, error details, actor, site/destination, action, time, and correlation under Time and Events. Raw payload logging is not a blanket requirement: redact credentials and sensitive content, and observe access/retention policy. Backend authentication may use OAuth, application passwords, or other approved mechanisms; no single mechanism is universal.

WordPress Evidence and Limits

The current service discovers block names/titles, templates, template parts, saved-pattern identifiers, and public stylesheet cues. Those snapshots are intermediate resource descriptions, not complete field schemas or validated tool examples. Its explicit remote content operation creates a page/post with draft status; that is not a general publish/approval implementation. Generation currently uses provider-specific prompting and resource labels; this does not establish provider-independent validated tooling. Optional-resource fallbacks do not prove complete site coverage or tool availability. WordPress implementation owns HTTPS/application-password details, endpoint mapping, style extraction, and backend-specific limitations. WordPress/native CMS inclusion and commercial support commitments remain scope decisions; no old customer or replacement obligation is assumed.

Positive and Negative Examples

Positive: a user reviews a site-valid normalized page, requests an authorised remote draft, and sees its actual draft result and provenance. Positive: a failed approval-request email leaves the governance request and business history intact and exposes communication failure. Negative: adapters store separate customer universes or let a provider's resource schema redefine the platform primitive. Negative: treating a model's well-formed markup or sanitised HTML as complete tool, permission, and policy validation bypasses the contract. Negative: silently substituting generic blocks when discovery failed claims fidelity without evidence.

Implementation and Acceptance

D01-D10 are settled. The first runtime uses an explicitly registered fake external adapter to prove Unknown/Reconciliation and repeatability without live effects. Implementation architecture specifies durable claims and Attempt records; WordPress retains optional backend-specific implementation knowledge. No live connector or complete publishing system is required before the first milestone.

Acceptance checks: distinguish messages/events; operate without AI; validate normalized examples; reject cross-site unavailable tools; retain source mapping; measure fidelity separately from coverage; expose partial/uncertain failures; protect credentials and governed access. Implementation architecture, Security and operations, and Implementation status own mechanisms and evidence.

Source Lineage

Source map and documentation ownership govern the ledger. 02 technical architecture, shared engines/AI boundary; 03 engines and MVP, Communication/Integration responsibilities; 01 product and principles and 00 combined handoff, holistic/no-AI intent provide the foundation. Older WordPress, CMS strategy, channel-connectors, publishing, notifications, and application Automations sources contribute normalized tools, capability limits, draft semantics, error handling, and delivery distinctions; current WordPress service inspection supplies only the explicitly labelled evidence above.