gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md

@@ -0,0 +1,231 @@
+# Microsoft Teams collaboration contract — scope and mapping
+
+Decision recorded **2026-09-07, before authoring the final model**. Domain
+`urn:gateway:connector:microsoft-teams`, version `1.0.0`; `gateway-world/1`.
+Shape: **base**. Assessment: **provisional subset**, researched against Microsoft
+Graph v1.0, tested with synthetic data. No tenant overlay is necessary for this
+bounded collaboration model. No live-response validation or tool behavior is claimed.
+
+This file owns the coverage and mapper policies. Source identities and hashes
+live in `provenance.json`; actual structural/synthetic checks and skipped live
+validation live in `fidelity.json`. No captured vendor goldens, replay score, or
+`mimic` claim is supplied. `world.json` and `teams-types.json` enforce the model;
+the scope, provenance, and fidelity files add no executable assertions.
+
+## Identity and scope matrix
+
+`C` below is `contextTenantId`, a required ingestion partition from the authorized
+capture tenant. It is **not resource ownership**. Vendor `tenantId` remains separate
+and can identify a host/creator/user/remote tenant. Every key component is a
+nonempty opaque string. No names, emails, labels, user IDs, or resource IDs have
+additional global uniqueness constraints.
+
+| Entity (`teams_` prefix) | Primary key after C | Graph v1.0 authority | Included state and nested types | Relationships / cardinality |
+| --- | --- | --- | --- | --- |
+| teams | id | team | id, classification, classSettings, createdDateTime, description, displayName, funSettings, guestSettings, internalId, isArchived, memberSettings, messagingSettings, specialization, summary, tenantId, visibility, webUrl | 1:N channels, team members, tags; primaryChannel retained as external contextual reference |
+| channels | teamId, id | channel | All documented stored structural fields: createdDateTime, description, displayName, email, isArchived, isFavoriteByDefault, layoutType, membershipType, migrationMode, originalCreatedDateTime, summary, tenantId, webUrl | Exactly one captured **host** team; 1:N members, root messages, sharing records |
+| incoming_channels | teamId, channelUrl | team-list-incomingchannels | Exact returned @odata.id as channelUrl; structured channel projection | Exactly one captured **receiving** team. Referenced host/channel can be outside capture; no fabricated host team |
+| shared_channel_teams | teamId, channelId, tenantId, id | sharedWithChannelTeamInfo | Remote team id, tenantId, displayName, isHostTeam; allowedMembers visibility | Exactly one captured channel; referenced remote team external. Remote tenantId required here to scope overlapping team IDs |
+| chats | id | chat | chatType, createdDateTime, isHiddenForAllMembers, lastUpdatedDateTime, migrationMode, onlineMeetingInfo, originalCreatedDateTime, tenantId, topic, webUrl; structured lastMessagePreview | 1:N members/messages/views. Meeting/calendar links external |
+| chat_views | chatId, viewerTenantId, viewerId | chat.viewpoint, chatViewpoint | viewpoint (isHidden, lastMessageReadDateTime), including explicit null | Exactly one captured chat; viewer is an external identity supplied by delegated request context |
+| team_members | teamId, id | conversationMember + concrete subtypes | displayName, roles, visibleHistoryStartDateTime; typed memberIdentity; originalSourceMembershipUrl annotation | Exactly one team; membership id is **not userId**; external user identity |
+| channel_members | teamId, channelId, id | channel members/allMembers | Same membership representation; originalSourceMembershipUrl preserves indirect-source attribution | Exactly one channel; never infer membership in host team, especially for shared channels |
+| chat_members | chatId, id | chat members | Same membership representation, including history visibility | Exactly one chat; roster-size and access rules deferred |
+| channel_messages | teamId, channelId, id | chatMessage, channel-list-messages | body, sender, mentions, reactions, attachments, eventDetail, history, policyViolation, timestamps, etag, importance, locale, messageType, subject, summary, webUrl, channelIdentity; replyToId/chatId absent or null | Exactly one channel; 1:N replies and hosted references |
+| channel_replies | teamId, channelId, replyToId, id | chatMessage-list-replies | Same message payload; required replyToId from enclosing root context | Exactly one root message in the **same** channel/team/C; no reply-to-reply chain |
+| chat_messages | chatId, id | chatMessage, chat-list-messages | Same message payload; replyToId/channelIdentity absent or null; summary absent or null | Exactly one chat. No invented chat threading semantics |
+| channel_hosted_contents | teamId, channelId, messageId, id | chatMessageHostedContent | Persisted hosted-content id; contentType when known | Exactly one root message; no file object or binary payload |
+| reply_hosted_contents | teamId, channelId, replyToId, messageId, id | chatMessageHostedContent | Same | Exactly one scoped reply |
+| chat_hosted_contents | chatId, messageId, id | chatMessageHostedContent | Same | Exactly one chat message |
+| tags | teamId, id | teamworkTag | description, displayName, memberCount, tagType | Exactly one team; 1:N tag members |
+| tag_members | teamId, tagId, id | teamworkTagMember | displayName, tenantId, userId | Exactly one tag; user is external, no local directory prerequisite |
+
+All actual foreign keys target the complete parent primary key with restrictive
+deletion. A coherent batch may insert children before parents. Deleting a parent
+requires explicit deletion of every dependent in the same transaction. The model
+has no cascading deletes, upserts, placeholder parents, or placeholder users.
+
+Separate message tables avoid nullable/discriminator key components and retain
+Graph's documented chat/channel/**reply-to-message** identity scopes. Even a root
+and its reply may share a vendor id. A shared table with a bare id or nullable
+parent would erase those distinctions. Hosted-content IDs inherit every parent
+component; evidence identity never replaces these keys.
+
+Incoming channels are observations of an external reference, keyed by the exact
+Graph @odata.id URL within the receiving team, not a second authoritative hosted
+channel. Do not parse opaque Teams webUrl values or make their display URLs into
+keys. Resolving an incoming reference into captured hosted channel state requires
+verified host context and its real parent record. Cross-tenant @odata.id transport
+quirks described by Microsoft remain future connector work.
+
+## Projection, requiredness, nullability, and visibility
+
+This is a **keyed projection contract**, not a Graph create-request contract.
+Only primary/foreign-key context and nested variant discriminators are required.
+All other supported properties may be absent (`$select`, permission differences,
+resource shape, or missing expansion). A Graph non-nullable property rejects null
+**when present**; nullable fields retain null. This allows id-only projections,
+not id-less records, and never invents values from Graph create defaults.
+
+Scalar nullability follows pinned production CSDL unless a documented discrepancy
+is recorded below. Collection properties are arrays, with item nullability from
+CSDL; they are not nullable collections. Missing, [], null items, empty strings,
+false, zero and explicit scalar null survive without coercion. Navigation
+collections are separated into entities and observation metadata; a Graph null
+navigation representation is recorded as such, never converted to [].
+
+Optional `relationshipCoverage` is a closed map of declared navigation names to
+`{status, nextLink?, count?}`. Status is `notRequested`, `partial`, `complete`, or
+`null`. Missing metadata means unknown. `complete` describes the requested view
+under its filter and authorization, never omniscient state. Retain next links;
+expanded replies can be independently paged. A complete *batch* does not prune.
+The contract checks metadata shape, **not its truth or agreement with row counts**.
+Absent collections must never become an implicit complete/empty assertion.
+
+`apply_batch.update` shallow-merges fields; nested properties replace whole nested
+values. A partial later capture must not erase uncaptured state. A future mapper
+must explicitly merge nested projections or supply a verified replacement, retain
+field/evidence lineage, and refrain from interpreting missing fields as deletion.
+
+## Nested payloads and normalization
+
+- Graph camelCase names and string IDs are retained. Entity-root `@odata.type`,
+  `@odata.id`, and `@odata.etag` become `odataType`, `odataId`, and `odataEtag`.
+  Nested payloads keep literal annotations where declared. Collection envelope
+  @odata.context and continuations remain capture evidence/coverage metadata.
+- Graph inheritance is flattened into direct closed entity objects. Membership
+  subtype-specific fields move into `memberIdentity`, a closed discriminated union
+  with `type` equal to the Graph short type name. Strip only the optional leading
+  `#microsoft.graph.` / `microsoft.graph.` from an observed membership @odata.type.
+  Do not infer subtype from email, userId, or displayName. If not observed, retain
+  the keyed common projection and defer subtype fields until verified.
+- Supported member variants: aadUserConversationMember (email, tenantId, userId),
+  anonymousGuestConversationMember (anonymousGuestId),
+  azureCommunicationServicesUserConversationMember (azureCommunicationServicesId),
+  microsoftAccountUserConversationMember (userId), phoneUserConversationMember
+  (phoneNumber), skypeForBusinessUserConversationMember (tenantId, userId), and
+  skypeUserConversationMember (skypeId). No identities are fabricated for guests,
+  external users, anonymous users, applications, or departed members.
+- `roles` is a string collection, not a closed enum. [] is an ordinary member;
+  owner/guest are qualifiers. Preserve combinations and future qualifiers.
+  Do not derive authorization or infer that every external owner administers the
+  resource. The common resource page's misleading id description does not justify
+  replacing the opaque membership id with userId.
+- Identity sets preserve user, application, device, and documented supporting
+  identity variants. Identity details, tenantId, userIdentityType,
+  applicationIdentityType, conversationIdentityType, and tag targets are structured.
+  External identity IDs are not foreign keys to an invented Entra directory.
+- Bodies retain `{contentType, content}` (HTML/text), not Slack-like text.
+  Mentions retain numeric id, mentionText and structured target. Reactions retain
+  user, timestamp, type, displayName and custom-content URL. Reaction type is an
+  open string (including emoji and custom), **not** a six-value closed enum.
+- Attachments retain all seven documented properties. `content` remains the
+  Graph **string**, including serialized card/forwarded-message JSON, rather than
+  reparsing it into an arbitrary object. contentType remains open to Bot Framework
+  media types. Attachments are not driveItem/file records. content/contentUrl
+  exclusivity is enforced by a nested union allowing either or neither non-null.
+- Known eventMessageDetail subtypes retain structured event payloads and identity
+  sets. Call/recording/transcript fields are references/metadata only, not meeting
+  infrastructure. Edm.Duration stays a string; Gateway cannot validate duration
+  syntax. Unknown concrete event or identity types/fields reject for review;
+  raw evidence must be retained for a future explicit contract revision.
+- Timestamps use Gateway's RFC3339 date-time profile, including fractions and
+  offsets; URLs/GUIDs/durations remain strings, with no invented format checker.
+  IDs have no inherited Slack length cap. Counts and mention indices are nonnegative. Integer fields use Int32 bounds where
+  Microsoft says Int32; no decimal/64-bit numeric values outside Gateway's safe
+  integer range are introduced.
+- Flags enums (message actions and DLP flags) become arrays of distinct known
+  strings, split from Graph comma-separated flags. A scalar null remains null;
+  `none`/`actionUndefined` remains its named value, not an invented empty array.
+  Member spelling follows CSDL wire values. No unknown string is silently changed
+  to unknownFutureValue. Evolvable enum sentinels are preserved when returned;
+  new named values require a researched version update. This does not authorize
+  sending sentinel values in Graph create/update operations.
+
+## Exclusions and adjacent-resource decisions
+
+| Family / field | Decision and implication |
+| --- | --- |
+| Team firstChannelName and team/channel creation-mode annotations | Create/migration operation inputs, not durable GET/list state; excluded. Read-only fields above remain ingestible. |
+| Identity thumbnails; identitySet.conversationIdentityType | Thumbnails belong to Drive imagery and are excluded. The generic identitySet page describes the sibling conversationIdentityType as an identity object while CSDL omits it; this ambiguous dynamic field is excluded. The documented Teams conversation.conversationIdentityType enum is included. |
+| FilesFolderReference extra driveItem properties; parentReference.sharepointIds; folder.view | File/reference projection only: opaque driveId/siteId/item ids, names, URLs, paths and childCount. SharePoint REST compatibility identifiers, folder presentation and workload facets are excluded. |
+| Team group, photo, schedule, template, operations, permissionGrants | Full group/Entra, images, Shifts, template lifecycle, async workflows and permission enforcement excluded. Team id is the associated group id; no group row required. |
+| Channel filesFolder | External SharePoint/Drive reference only (id, name, webUrl, parentReference, folder shape subset), no file content/library implementation. |
+| Team primaryChannel | Structured external channel reference; projection may be available without a fully captured channel row. |
+| Channel allMembers / sharedWithTeams.allowedMembers | Direct and indirect membership records preserved; allowedMembers list represented by visibility only in this milestone. No derived/expanded effective ACL calculation. |
+| Chat viewpoint | Split into viewer-scoped chat_views; never overwrite a shared chat with whichever caller was last captured. |
+| Chat pinnedMessages / targetedMessages | Excluded; pin/unpin events may be retained without claiming a complete pin inventory or targeted-message delivery. |
+| Tabs and installed/enabled apps | Inventories/configuration/consents excluded. Message attachment teamsAppId and tab/app event references preserved. Chat/team collaboration does not require fake app or tab rows. |
+| Tags/tag memberships | Included for collaboration mentions. Scheduled tag type retained as documented reference state; Shifts creation/behavior excluded. |
+| Hosted content contentBytes / temporaryId | Binary request payload and transient upload identifier excluded. Stable IDs and contentType when independently known are retained; retrieval bytes belong in evidence/storage, not a file workload. |
+| Open extensions, arbitrary dynamic properties, beta-only fields | Excluded from closed model; reject and retain evidence for review. Team classification remains an open string; no required Entra overlay. |
+| Outlook, Planner, OneDrive/SharePoint, telephony, recordings, meetings | No workload entities/operations. Necessary URLs, IDs, event metadata and organizer identities remain external references. |
+
+## Evidence discrepancies and chosen interpretation
+
+1. **Membership id**: common resource tables call it a user ID; endpoint guidance
+   says membership IDs are opaque, and concrete-member docs distinguish id from
+   userId. Keep the membership record id scoped by its parent.
+2. **Open identity types**: production CSDL lists only inherited id/displayName
+   (and minimal identitySet slots), while Microsoft documents tenantId and richer
+   Teams variants as dynamic/open properties. Explicitly author those documented
+   fields; do not permit arbitrary JSON everywhere.
+3. **Team classSettings** is in the v1.0 resource docs but absent from production
+   team CSDL; include the documented v1.0 type/setting. **scheduled** teamworkTagType
+   is documented in v1.0 but absent from pinned metadata; include it, without
+   implementing Shifts. **unknownFutureValue** message importance is in production
+   CSDL but omitted from its property table; accept the CSDL sentinel.
+4. **phoneUserConversationMember** is in production v1.0 CSDL but has no resource
+   page at the pinned docs revision (404). Include the metadata-backed phoneNumber
+   variant, recording this evidence limit; do not label it beta or live-validated.
+5. **DLP enum spelling/flags**: prose capitalizes names and describes flag behavior;
+   CSDL defines lowercase wire names and IsFlags. Normalize to arrays of those
+   exact members; contradictory permission flags remain mapper validation work.
+6. **Expanded reply page size**: channel-list-messages describes both 200 and 1,000
+   replies in different sections. Do not enforce either size; follow returned
+   replies@odata.nextLink and record partial visibility until pagination ends.
+7. Nullable=false means value nullability, not unconditional field presence under
+   partial projection. Keys are deliberately stricter ingestion prerequisites.
+   Collection Nullable applies to items, not whether a collection itself is null
+   (OASIS CSDL XML 4.01 §7.2.1); navigation nulls are retained in observation metadata.
+
+## Enforcement boundary and future mapper obligations
+
+Before persisting, a mapper must establish authorized C, actual vendor id, and
+all parent context from the request path/verified expansion. Channel teamId is the
+**host**, never an incoming-channel receiving team. Reply replyToId comes from the
+root route and must agree with a provided body value. Chat chatId and tag teamId
+are similarly supplied when omitted. Verify redundant channelIdentity/tenant/id
+claims against route context; the dialect cannot compare arbitrary nested fields.
+Shared-team edges without a known tenantId and all other keyless projections stay
+in evidence until identity is resolved. Never invent a concatenated vendor ID.
+
+Map only supported properties and record exclusions in the capture/mapping report;
+unknown or malformed payloads must not be silently accepted or discarded. Separate
+navigation entities from their parent's structural properties, with explicit
+visibility. Do not infer current roster from sender identity, historical role
+events, tag counts, or partial captures. Standard/private/shared and group/1:1/
+meeting cardinality/access rules, mentions matching HTML, event/type consistency,
+chronological timestamps, tenant consistency, URL/duration/base64 syntax, summary
+counts, and vendor permission/operation rules are **not enforced** by this contract.
+
+DeletedDateTime preserves message deletion state and body redaction/projections;
+it does not delete local rows. Explicit provider deletions require explicit
+mutations and dependent deletes. Role changes and edits are authored updates,
+not simulated vendor operations; `readOnly`, `writeOnly`, and defaults have no
+mutation authorization or automatic-value behavior.
+
+Persist only through `apply_batch` or schema-gated `ingest`. Batches require the
+exact compiled `target = {id, version, hash}`, stable mapping id/version, ordered
+explicit insert/update/delete mutations, and stable per-record `source.record`.
+`source.evidence` uses `{reference, digest}` with SHA-256 **lowercase hex**
+of the verified source bytes. Capture ArtifactReference digests use **base64** of
+the same 32 bytes: decode/verify then encode hex, never hash the base64 text.
+Evidence references identify observations, not entity primary keys. An exact
+canonical batch retry returns `already_applied` with zero mutations; altered
+content or mutation order under that ID rejects with `idempotency_conflict`.
+`ingest` provides an atomic audit with per-key rather than per-mutation provenance;
+reusing a committed session ID rejects, and raw sessions are not replayable.
+Complete coverage never implies deletion. Invalid batches or SQL sessions roll
+back state, lineage and retry identity. Expiring evidence may be unavailable even
+though durable lineage survives; recapture is future work.