@terminal3/t3n-sdk 5.0.0 → 5.1.0

package/dist/index.d.ts

@@ -1483,6 +1483,12 @@ interface OrgDataActionWire {
  * calling agent to be the `grantee` of at least one grant (subject binding), so
  * an unregistered agent discovers nothing regardless of this list.
  *
+ * Every entry must be a canonical `did:t3n:<40-hex>` identifier. The contract
+ * decodes each one to its 20 bytes, so a value of any other shape refuses the
+ * whole document (the error names the failing index), and two hex casings of one
+ * DID are a duplicate rather than two entries — also a refusal. Use
+ * {@link mergeDiscoverDids} to build the list rather than concatenating.
+ *
  * The document IS the new state on a write: an empty `grants` list revokes all
  * delegated access, and an empty `discover_dids` persists an empty
  * discovery-grant list (there is no per-field merge). Use {@link mergeGrants} /
@@ -1519,8 +1525,20 @@ declare function mergeGrants(existing: BoundGrant[], additions: BoundGrant[]): G
 /**
  * Order-preserving deduplicating union of discovery-grant DID lists — the
  * read-merge-write counterpart of {@link mergeGrants} for the document-level
- * `discover_dids` (the contract rejects duplicate entries, so the union must
- * dedupe).
+ * `discover_dids`.
+ *
+ * A DID's identity is the 20 bytes it decodes to, not its spelling. The contract
+ * dedupes on those bytes and treats a repeat as a hard error over the WHOLE
+ * document, so unioning `did:t3n:AABB…` with `did:t3n:aabb…` has to yield one
+ * entry — matching on the raw string would emit both and lose the write. Each
+ * recognised entry is emitted in canonical lowercase, the form the contract
+ * stores and a later `member-delegation-get` returns, so repeated
+ * read-merge-write cycles converge instead of oscillating.
+ *
+ * An entry that is not a `did:t3n:<40-hex>` identifier at all passes through
+ * verbatim and dedupes by exact string: the contract refuses it and names its
+ * index, which is more use to the caller than this helper dropping it or folding
+ * it into an unrelated entry.
  */
 declare function mergeDiscoverDids(existing: string[], additions: string[]): string[];
 /**
@@ -1617,10 +1635,16 @@ interface AgentAuthEntry {
  * in `agents` (subject binding), so an unregistered agent discovers nothing
  * regardless of this list.
  *
+ * Every entry must be a canonical `did:t3n:<40-hex>` identifier. The legacy
+ * document is converted onto the current one before it is stored, and that
+ * conversion decodes each entry, so anything else refuses the write with the
+ * failing index named.
+ *
  * @deprecated Use {@link MemberDelegationDoc}.
  */
 interface AgentAuthPolicy {
     agents: AgentAuthEntry[];
+    /** Document-level discovery grants (`did:t3n:<40-hex>` entries). */
     discoverDids: string[];
 }
 /**
@@ -1668,6 +1692,10 @@ interface AgentAuthUpdateInput {
  * deny-all egress. The document-level `discover_dids` is emitted only when
  * non-empty; the contract defaults an absent list to empty.
  *
+ * Discovery DIDs are copied through verbatim — no canonicalisation, no dedupe —
+ * so a non-canonical or repeated entry is refused by the contract rather than
+ * quietly repaired here. Build the list with `mergeDiscoverDids`.
+ *
  * @deprecated The new write path passes `MemberDelegationDoc` straight through
  * with no casing transform.
  */