RFC: ATProto compatibility layer — core type and API changes

[cuibonobo]

Motivation

As Haverstack moves toward federation and multi-stack interop, ATProto (the protocol behind Bluesky) is the most architecturally aligned target. Both are record-centric, identity-scoped, and schema-namespaced. This issue proposes a set of additive, non-breaking changes to @haverstack/core that would make a future @haverstack/adapter-atproto straightforward to implement.

---

Proposed changes

1. Content addressing — add cid to StackRecord

ATProto's foundational property is content addressing: every record has a CID (Content Identifier) derived from its content. Without this, Haverstack can't participate in ATProto's signed commit log or verify record integrity across stacks.

// types.ts
export type StackRecord = {
  id: RecordId;
  cid?: string; // SHA-256 CID of the content blob, computed on write
  // ...existing fields
};

The stack should compute and store cid on create and update. ATProto adapters can use this to build a proper commit chain.

---

2. Surface previousCid on update()

ATProto records are immutable at a given CID — updating means writing a new CID and recording the transition. The current update() return type should surface this:

async update(id: string, content: ...): Promise<StackRecord & { previousCid?: string }>

This is largely an adapter-level concern, but exposing it in the return type keeps the door open without requiring a future breaking change.

---

3. at:// URI support

ATProto identifies records by URI: at://<did>/<nsid>/<rkey>. Haverstack IDs are within-stack only (this is already noted in the README). Two additions:

A helper method on Stack:

getAtUri(record: StackRecord): string {
  return `at://${this.ownerEntityId}/${record.typeId}/${record.id}`;
}

atUri on RelationshipAssociation for cross-stack references:

export type RelationshipAssociation = {
  kind: 'relationship';
  label: string;
  recordId: RecordId;
  stackUrl?: string; // already implied — make explicit
  atUri?: string;    // ATProto native reference form
};

---

4. DID support on EntityContent

ATProto identity is built on DIDs (did:plc:... or did:web:...). Handles are resolved to DIDs; DIDs are the stable identity. EntityContent should support this natively:

export type EntityContent = {
  name: string;
  handle?: string;
  did?: string; // e.g. "did:plc:abc123" or "did:web:example.com"
};

Stack.ownerEntityId is currently a local RecordId. A companion ownerDid?: string on the Stack class (read from adapter config) would make ATProto stack identity unambiguous.

---

5. unlisted permission + tombstone on StackRecord

ATProto distinguishes tombstoned records (URI remains valid, content is gone) from deleted ones. It also has no direct equivalent of { access: 'public' } without a concept of "accessible by URI but not indexed."

export type Permission =
  | { access: 'public' }
  | { access: 'unlisted' } // accessible via URI, not surfaced in feeds/indexes
  | { access: 'entity'; entityId: RecordId; read: boolean; write: boolean }
  | { access: 'group'; groupId: RecordId; read: boolean; write: boolean };

export type StackRecord = {
  // ...
  tombstone?: boolean; // URI remains valid, content is redacted — distinct from deletedAt
};

---

6. lexiconId on StackType

ATProto Lexicons use reverse-DNS without a version suffix in the $type field (e.g. app.bsky.feed.post). Haverstack's com.example.myapp/note@1 format doesn't need to change, but storing an optional Lexicon ID alias lets an ATProto adapter map outbound records to the correct $type without apps having to change their internal naming:

// types.ts
export type StackType = {
  // ...existing fields
  lexiconId?: string; // e.g. "app.bsky.feed.post"
};

// stack.ts
export type DefineTypeOptions = {
  migratesFrom?: TypeId;
  lexiconId?: string;
};

---

Summary

Change	Breaking?
cid on StackRecord	No — optional field
previousCid on update() return	No — additive to return type
getAtUri() + atUri on relationships	No
did on EntityContent	No — optional field
unlisted + tombstone	No
lexiconId on defineType / StackType	No

All changes are additive. They lay the groundwork for @haverstack/adapter-atproto without requiring any migration of existing stacks or changes to app code.

[cuibonobo]

Follow-up: generalizing for protocol-agnostic external references

After thinking through a concrete use case (a personal CRM bridging ATProto and Haverstack), it's clear that some of the proposed changes are too ATProto-specific. Since Haverstack's portability goal extends beyond any single protocol, here's a revised take on the identity and relationship proposals.

---

Revised #3: generic external references on RelationshipAssociation

Rather than an atUri field, model the concept of "a reference to something outside this stack" generically:

export type RelationshipAssociation = {
 kind: 'relationship';
 label: string;

 // Internal reference (unchanged)
 recordId?: RecordId;
 stackUrl?: string;

 // External reference (replaces atUri)
 externalId?: string; // the identifier itself
 externalNs?: string; // the scheme that interprets it
};

This covers ATProto, ActivityPub, Nostr, plain URLs, email — anything:

{ externalId: "at://did:plc:abc123/app.bsky.feed.post/3k4", externalNs: "atproto" }
{ externalId: "https://mastodon.social/users/alice/statuses/123", externalNs: "activitypub" }
{ externalId: "note1abc123...", externalNs: "nostr" }
{ externalId: "alice@example.com", externalNs: "email" }

Haverstack expresses the concept; the adapter or app interprets the value. No protocol is privileged.

---

Revised #4: generic external identities on EntityContent

did is already protocol-agnostic (DIDs predate ATProto and are used by ActivityPub implementations too), but singling it out as a named field implies ATProto primacy. A more general shape:

export type EntityContent = {
 name: string;
 handle?: string;
 externalIds?: Array<{ id: string; ns: string }>;
};

Examples:

{ id: "did:plc:abc123", ns: "did" }
{ id: "did:web:alice.example.com", ns: "did" }
{ id: "alice@example.com", ns: "email" }
{ id: "npub1abc123...", ns: "nostr" }

An ATProto adapter would look for ns === "did". An ActivityPub adapter would do the same. A CRM app can index all of them without caring which protocol surfaced them.

---

Unchanged proposals

The remaining proposals (#1, #2, #5, #6) are ATProto-specific by nature — content addressing, lexiconId, and tombstoning are protocol primitives, not general-purpose concepts. They belong in @haverstack/adapter-atproto rather than core, and should be dropped from this issue. A separate issue scoped to that adapter would be the right place.

---

Revised summary

Change	Scope
cid / previousCid	core → move to adapter-atproto
getAtUri() + externalId/externalNs on relationships	core
externalIds on EntityContent (replaces did)	core
unlisted + tombstone	core → move to adapter-atproto
lexiconId on StackType	core → move to adapter-atproto