@pam-ai/pam-ordo-contracts 3.4.0

package/README.md

@@ -0,0 +1,72 @@
+# Pam Ordo contracts
+
+The versioned OpenAPI contract, generated TypeScript types, and shared fixtures for Pam Ordo APIs.
+
+## Install
+
+Pin consumers to an exact npm version:
+
+```json
+{
+  "dependencies": {
+    "@pam-ai/pam-ordo-contracts": "3.4.0"
+  }
+}
+```
+
+```ts
+import type {
+  ConversationDetailResponse,
+  InboxListResponse,
+  NotificationListResponse,
+  CommandResult,
+  ErrorEnvelope,
+  paths,
+} from '@pam-ai/pam-ordo-contracts';
+```
+
+FIFO producers also import `ProducerCommandV1` plus the deterministic
+`producerMessageGroupId`, `producerMessageDeduplicationId`, and
+`producerMessageAttributes` helpers. The helpers keep every producer aligned
+with the ordered-consumer contract without introducing an AWS SDK dependency.
+
+Policy and authority consumers import `InboxPolicyV1`,
+`InboxTargetResolutionRequestV1`, and `InboxTargetResolutionResponseV1`.
+Use `inboxPolicyVersion` to derive the immutable `sha256:` policy snapshot ID
+from canonical normalized policy content. `InboxPolicyV1` intentionally rejects
+legacy timed-escalation fields.
+
+The public npm artifact contains compiled TypeScript declarations, bundled OpenAPI, and shared fixtures. Consumers do not need GitHub repository credentials.
+
+## Contract development
+
+`openapi/openapi.yaml` is the source of truth. Bundled JSON and generated TypeScript are committed for review.
+
+```bash
+npm install
+npm run contract:generate
+npm run check
+npm pack --dry-run
+```
+
+## Quality commands
+
+The repository follows the dashboard conventions for linting, formatting, and dependency auditing:
+
+```bash
+npm run lint
+npm run lint:fix
+npm run format
+npm run format:check
+npm run npm-audit
+```
+
+Generated TypeScript and bundled OpenAPI are excluded from ESLint and Prettier; their generators enforce deterministic output. CI uses Pam's shared lint and audit actions.
+
+Breaking changes require a major version bump:
+
+```bash
+npm run contract:breaking -- --base <full-base-commit-sha>
+```
+
+Follow [docs/PUBLISHING.md](docs/PUBLISHING.md) to publish an immutable npm version and matching Git tag. Consumers should pin the exact npm version.