@appport/protocol

The AppPort wire contract: envelope types, error codes, naming rules, manifest shapes, structural validation and compatibility analysis.

This package is pure. It has no runtime dependencies and knows nothing about transports, servers or clients — which is what makes it safe to depend on from a browser bundle, an Electron preload script or a CLI.

import { createRequest, parseClientEnvelope, PROTOCOL_ID } from "@appport/protocol";

const request = createRequest({
  requestId: "req_01J...",
  capability: { name: "documents.save", version: 1 },
  input: { documentId: "doc_1", content: "hello" }
});

parseClientEnvelope(request); // throws AppPortError on a malformed envelope

What is here

| Module | Contents | | ---------------- | --------------------------------------------------------------- | | version | appport/1, conformance levels | | envelopes | request, response, event, subscribe, stream envelopes and guards | | validate | protocol-level structural validation, decode and encode | | errors | the standard error codes and AppPortError | | names | capability, event, permission and application-id grammar | | ids | ULID-based identifier helpers | | manifest | manifest, discovery and transport descriptor types | | jsonschema | the JSON Schema subset published in manifests | | session | Principal and Session | | operations | long-running operation records | | blob | binary references | | compatibility | breaking vs non-breaking manifest diffing; compareSchemas for one schema pair | | fulfillment | canonical contracts (isCanonicalContract), fulfillment claims (claimFor, claimsFor, lintFulfillment) and their evaluation (evaluateFulfillment) (spec/fulfillment-1.md), since 1.2.0 | | integration | integration metadata and lintIntegration; dependencies, including canonical targets (CanonicalDependencyTarget, isCanonicalDependencyTarget, since 1.2.0) |

Names are checked, not merely typed: electron.documents.save and ipc.saveDocument are rejected, because a capability name that encodes a transport breaks the protocol's central invariant.

Public discovery (1.1.0)

buildPublicDescription, validatePublicDescription, capabilityDigest, contractDigest, PUBLIC_DESCRIPTION_PATH and the appport.public-description/1 schema (spec/schemas/public-description.schema.json in the repository). Publication is the application owner's explicit, fail-closed decision; a description is a pointer to, and a digest of, the authoritative manifest and is untrusted data. Discovery is not authorization, approval or publisher trust.

Agent Feedback Protocol (1.5.0)

appport.feedback/1: a consuming agent reports friction with an API in a structured, versioned report; the provider answers with a receipt, lifecycle updates and a resolution with a retry recommendation. This package holds the deterministic primitives only: validateFeedbackReport, validateFeedbackReceipt, validateFeedbackUpdate, validateFeedbackStatus, validateFeedbackDiscovery, the lifecycle table (FEEDBACK_TRANSITIONS, applyFeedbackUpdate), digests (feedbackReportDigest, feedbackFingerprint, evidenceDigest), discovery checks (lintFeedbackSupport, checkReportAgainstDiscovery) and authority checks (bindFeedbackSubmitter, authorizeFeedbackRead, decideFeedbackSubmission, checkFeedbackFreshness). Nothing here stores, delivers, authenticates or calls a model. Feedback is advisory input, never execution authority. FEEDBACK_SCHEMA / feedbackContractSchema(definition) expose the normative schema for publishing the reserved capabilities. Specification: spec/agent-feedback-1.md.