@dmsdc-ai/aigentry-ssot

Typed Interface Authority for the aigentry ecosystem. Build-time contract validation, JSON Schema codegen, and the envelope-in-PTY transport utilities.

This package is build-time only — no runtime daemon, no HTTP server, no admission webhook. Consumer repos import types, validate inject payloads in CI, and generate per-language bindings from the published JSON Schemas.

Install

npm install --save-dev @dmsdc-ai/aigentry-ssot

Contract modules

| Module | Purpose | | ------------------------------------- | ---------------------------------------------------------------------------------------- | | @dmsdc-ai/aigentry-ssot/contracts/session | SessionId, SessionContext, Session | | @dmsdc-ai/aigentry-ssot/contracts/lifecycle | LifecycleEvent, LifecycleEnvelope, Hold, Report, CleanupRequest | | @dmsdc-ai/aigentry-ssot/contracts/capability | Capability enum, Role enum, ROLE_CAPABILITY_SUBSET, isSubsetOfRoleDefault() | | @dmsdc-ai/aigentry-ssot/contracts/workspace-host | WorkspaceHost (4-method surface: lookup / close / alive / list_ids) | | @dmsdc-ai/aigentry-ssot/contracts/telemetry-event | TelemetryEvent (NDJSON envelope schema) | | @dmsdc-ai/aigentry-ssot/contracts/handoff | TestReport, EvidenceRequest, EvidenceResponse | | @dmsdc-ai/aigentry-ssot/envelope/pty-envelope | parsePtyEnvelope, serializePtyEnvelope, extractFencedJsonBlocks |

CI lint hook integration (consumer side)

A consumer repo (aigentry-orchestrator, aigentry-telepty, aigentry-dustcraw, …) integrates ssot validation in CI as follows:

1. Pin the exact version of @dmsdc-ai/aigentry-ssot in devDependencies.

2. Commit canonical inject fixtures under fixtures/inject/*.json.

3. Add a PR-time CI job:

   - name: ssot conformance
     run: |
       for f in fixtures/inject/hold/*.json; do
         npx tsx node_modules/@dmsdc-ai/aigentry-ssot/scripts/lint-consumer.ts \
              --schema hold < "$f"
       done

   The payload is piped via stdin to keep the tool side-effect-free with respect to filesystem paths (Snyk SAST hardening per CLAUDE.md At-Inception policy).

The job fails on schema violations. No runtime gate, no daemon, no network calls — pure build-time validation per ADR §1 (lightweight).

Envelope-in-PTY transport

The recommended way to ship structured payloads over telepty inject:

import {
  serializePtyEnvelope,
  parsePtyEnvelope,
} from '@dmsdc-ai/aigentry-ssot/envelope/pty-envelope';

const wire = serializePtyEnvelope(
  { schema_version: '1', kind: 'hold', payload: { phase: 'X', reason: 'Y', needs: 'Z' } },
  { preamble: 'orchestrator: please ACK', trailer: '— α1' },
);

// On the receiver:
const result = parsePtyEnvelope(wire);
if (result.ok) {
  // result.envelope.kind === 'hold'
  // result.envelope.transport === 'json-fenced'
}

Legacy markdown HOLD/REPORT formats still parse via the markdown-fallback transport tag — backward compat per decision #3 option C (2026-05-23).

A2A reference

See docs/a2a-mapping.md for the structural alignment between this package and the A2A protocol.

SemVer

See SEMVER.md. Pre-1.0 the policy is conservative; once 1.0.0 ships, every breaking change requires a MAJOR bump.

Build & test

npm install
npm run typecheck     # tsc --noEmit
npm run build:schemas # regenerate schemas/v1/*.schema.json
npm test              # vitest run