gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/slack/MODEL.md

@@ -0,0 +1,236 @@
+# Slack collaboration domain v2
+
+This finite collaboration model now includes a Slack-shaped executable subset through
+Gateway hosted mock-tools. Synthetic fixtures are invented; no live fidelity is
+claimed. Official Slack documentation takes precedence over the pinned emulator
+reference. [capabilities.json](capabilities.json) classifies every entity and tool.
+Its authoring format shares entity/operation defaults; initialization and publication
+expand those defaults into self-contained version-1 capability entries.
+
+[world.json](world.json) defines the contract. [scope.toml](scope.toml) bounds it;
+[provenance.json](provenance.json) pins sources. These metadata files and this guide
+are not compiler dependencies or lock inputs. The schema hash identifies
+the template before initialization customizes its package ID.
+
+## Use
+
+With the SDK installed, initialize an empty world:
+
+```sh
+python -m gatewaysdk.environment.schema init ./slack-world --connector slack
+python -m gatewaysdk.environment.schema check ./slack-world
+```
+
+From the Gateway repository root, generate an example in a new or empty directory:
+
+```sh
+python samples/schema-worlds/rebuild_slack.py /tmp/slack-example
+python -m gatewaysdk.environment.schema check /tmp/slack-example
+```
+
+The builder compiles the SDK template and maps authored
+`samples/schema-worlds/slack/data/records.json` into its initial batch. The source
+fixture directory is not runnable. Use `describe` for inventory.
+
+## Identity and normalization
+
+`workspace_id` means the containing modeled workspace, not an actor's home team.
+Vendor team/enterprise fields retain their meanings; remote references need no
+fabricated workspace rows. Object roots use vendor `id`. Emulator row IDs,
+persistence bookkeeping and lookup indexes do not become domain constraints.
+
+Messages use `(workspace_id, channel_id, ts)`. Timestamp bytes are identity:
+numerically equivalent spellings remain distinct keys. Unix seconds use integers;
+conversation `updated` uses milliseconds. `list_messages` compares decimal strings
+without floats and breaks numeric ties using original bytes. The domain
+accepts any nonempty timestamp string, while that helper rejects malformed decimals.
+
+Structural associations require complete local targets. Historical authors,
+editors, uploaders, reaction actors and remote identities remain typed observations:
+materializing them does not require inventing users, bots, apps or memberships.
+Viewer state, recipients, presence, group membership and view ownership require
+local users. The narrower `post_message` helper accepts a top-level human text
+message from a current member; this is not a universal rule for imported messages.
+
+`slack_message_threads` is the only persistent thread authority. Reconstruct a
+reply's `thread_ts` from its association's `parent_ts`. Top-level messages need no
+association. A parent's self marker can be inferred from replies; its presence
+on a reply-less projection is lost. Scheduled/ephemeral thread associations
+point to persistent messages in the same containing workspace and conversation.
+No root-only, depth or cycle restrictions are enforced.
+
+Reaction/reply/member counts and file-share statistics are observations,
+independent of local rows or actor samples. User-group `user_count` allows strings
+and integers because the official example and field table disagree; string
+numeric syntax is not enforced.
+
+Profile fields, group memberships and view `values[block_id][action_id]` become
+keyed rows. Optional `fields_state`, `users_state` and `values_state` markers
+preserve absent/null/observed distinctions: `present` with no children can mean
+an empty collection. Markers do not enforce completeness or consistency.
+
+## Rich content and files
+
+Entity roots are closed; known rich-content envelopes are typed. Selected nested
+vendor objects remain open to preserve future blocks, elements, metadata and view
+state. This does not validate every Block Kit shape or conditional requirement.
+`request_options` separates emulator-retained request settings from returned message
+data. Nonrecursive `message` and `previous_message` preserve lifecycle observations
+without creating another authority for thread, file or reaction relationships.
+
+Structured connector capture applies a narrower explicit projection before mapping.
+Known block/text/attachment fields and common nested rich-text fields survive;
+unknown field names are reported without their arbitrary values. Capture allows up
+to 50 blocks, 100 attachments and 1,000 child items, with structural depth eight
+and 10,000 input nodes per message's rich content. Content URLs remain inert strings;
+private file URLs, credentials and arbitrary message metadata are excluded. The
+canonical contract still rejects invalid projected values, including null message
+author IDs; missing, null, false, zero and empty values remain distinct where allowed.
+
+`slack_files` owns full metadata; `mode`, `mimetype` and `size` are required for
+that canonical shape, not every Slack projection. Missing metadata must not be
+invented. Mode remains an open string rather than the emulator's restricted enum.
+File URLs are metadata; no file bytes are fetched or stored.
+
+`slack_message_files` records attachment occurrences; `slack_file_shares` adds
+observations to them. Share `ts` becomes `message_ts`; `observed_thread_ts` is
+not another thread authority. `slack_file_channel_observations` records
+`channels/groups/ims` without implying an available share message. Local targets
+remain required; counts and privacy flags need not agree with these observations.
+
+Unavailable-file variants preserve identity and an access discriminator without
+inventing a full file. Redundant `mode=file_access` plus
+`file_access=check_file_info` and empty/zero metadata sentinels normalize to one
+discriminator; their original distinctions are lost. Ephemeral messages have
+separate full-file associations and nested unavailable references. Full/unavailable
+occurrence exclusivity and position uniqueness are not enforced across rows.
+
+Official `initial_comment` is an uploader-comment observation; the emulator's
+upload-request string is separate `upload_initial_comment`. Standalone legacy
+file comments and file/file-comment pins are excluded; pins target messages only.
+
+## Limits and compatibility
+
+Views/navigation IDs are snapshots, without state-to-block checks, modal stacks,
+trigger expiry, hash concurrency or conditional title/submit rules. Scheduled
+messages never publish themselves. Ephemeral snapshots are not persistent history
+or a delivery guarantee. App metadata excludes connection/installation lifecycle.
+
+The compiler/store enforce declared types, closed roots, immutable keys, complete
+foreign keys and restrict deletion. Delete dependents explicitly with their parents
+in an atomic batch. Rejections roll back state and lineage. Flag consistency,
+actor XOR, permissions and count equality are not enforced. Embedded metadata does
+not implement the adjacent Slack product/admin domains excluded in `scope.toml`.
+
+The domain version is **2.0.0**, mapping version **1**, and executable package
+**2.1.1**. The cleanup preserves all 34 entity contracts and resolved tool input/output
+shapes; shared schema references and metadata defaults reduce repeated authoring.
+The `slack` slug and
+`urn:gateway:connector:slack` stay stable. V1 synthetic message IDs, RFC3339 fields,
+mandatory local user authors and single-channel files are not migrated. V1 batches
+and persisted worlds need their original bundle or an explicit reconstruction;
+recompiling v2 is not a state migration. Persisted state must match its compiled lock.
+Package 2.1.0 worlds retain their original bytes and behavior. New initialization
+uses the current package; refresh requires its exact trusted template digest and
+rejects an older or changed pin. No published version is rewritten automatically.
+
+## Executable bundle and fixed principal
+
+`build_slack_bundle(path, evidence=None)` initializes and validates a populated world.
+Omitting evidence uses an invented release workspace with users, public/private/DM
+conversations, memberships, a discussion/thread, rich content, reactions and files.
+`gateway worlds schema init --connector slack` still creates an empty contract.
+The separate exhaustive `records.json` fixture graph covers all 34 entity shapes.
+
+The build writes a bundle-owned `tools/slack-principal.json`. Slack-shaped tools do
+not accept arbitrary actor/workspace inputs; compatibility fixture helpers enforce
+the same principal when this file exists. Private conversations require membership;
+local writes require membership and reject archived/frozen/read-only conversations.
+This is a bounded permission model, not Slack OAuth or a complete scope simulator.
+
+Reads project canonical associations into Slack message envelopes. History returns
+newest first and excludes ordinary thread replies; replies return root plus children
+oldest first. Timestamp boundaries compare exact fractions. Query-bound cursors are
+local offset tokens, not Slack cursor bytes; mutation between pages has no snapshot
+guarantee. New message timestamps use a deterministic logical clock. Text-only edits
+clear blocks; omitted attachments remain. Reaction operations mutate the current
+actor's membership and increment/decrement observed counts without fabricating a
+complete actor sample. Deleting a message removes its own dependent associations.
+Deleting a root with dependent threads returns `unsupported_thread_root_delete`.
+
+Paginated history, replies, users and conversations select raw rows before assembling
+their responses. Each read call lazily groups needed associations from the supported
+store API once per entity. File discovery reuses those groups while evaluating
+visibility and total counts. These maps are local to one read; no cache survives a
+mutation, reset or refresh. Exact ordering, cursor scope and sampled counts remain unchanged.
+
+File tools expose metadata and existing message associations, without downloads or
+uploads. Pins have list/add/remove behavior; bookmarks, user groups and presence are
+read-only observed projections. Scheduled/ephemeral messages, apps/bots, viewer
+snapshots and views do not imply delivery, administration or interactive behavior.
+Consult the capability inventory for each family's precise classification.
+Join/leave, pins, bookmarks, user groups and presence remain exposed; cleanup does
+not remove optional operations or turn unsupported snapshots into executable features.
+
+## Evidence mapping and refresh
+
+The versioned mapper consumes `gateway-slack-evidence/1` envelopes containing
+workspace/principal identity and successful Slack response observations. Each has
+method/context/data plus a stable evidence reference and lowercase SHA-256 digest;
+a top-level source is accepted for single-artifact envelopes. Capture verifies bytes
+and authorization; the mapper performs no network requests and accepts no tokens.
+
+The mapper normalizes profiles, viewer state, threads, reaction samples, full and
+unavailable files, observed shares, pins, groups and bookmarks through one atomic
+store batch. Missing structural targets or full-file requirements reject the batch.
+Historical actor IDs are retained without fabricated users. Overlapping observations
+merge in capture order; later explicitly observed fields win. Nested projected object
+fields merge recursively, while explicit null/empty scalar/list values remain values.
+Partial API pages never authorize removal of unobserved keyed rows. Explicit nested
+profile field maps, message attachment arrays, empty reaction arrays and is_member=false
+observations generate source-backed removals for those exact associations. Full-to-
+unavailable file transitions replace the attachment reference while retaining prior
+file metadata as historical state. Group membership arrays remain observed samples.
+
+`refresh_slack_bundle(path, evidence, batch_id=...)` is for an isolated copy used to
+build a new version. It reconstructs validated state and lineage, then appends a
+sorted `data/batches/*.json` artifact after atomic validation. The original initial
+batch remains untouched. Exact retries are no-ops; reusing an ID for different bytes
+rejects. Principal/workspace changes reject. Missing messages, empty history pages,
+access loss and complete-page claims do not prune. Explicit `message.deleted`
+observations may remove an existing message and its own associations; unresolved
+thread dependents still reject atomically. Running session mutations are not merged
+into connector refreshes: the parent version snapshot is the refresh base, and newly
+observed fields supersede previous imported fields there. Mapping version changes
+require explicit package/update review; no automatic migration is provided.
+
+`fidelity.json` binds package, domain target, exact lock and source hash, reports
+coverage/unknown fields, and leaves live replay skipped with a null score. Builds
+are `synthetic` without live evidence and `subset` with captured evidence until real
+comparison supports a higher label. Schema and store checks are mandatory; fidelity
+reports are advisory. Synthetic goldens live under the sample's `goldens/` directory.
+The authored capability inventory is the single source for `platform_capture` and
+`capture_methods`. A vendor `capture_source` identifies a possible source, not proof
+that the hosted pipeline requests it. Observed mutation counts and invented fixture
+counts remain separate from collection policy.
+
+## Semantic scenario
+
+Populated builds with a writable observed root include `scenario.json` and
+`tasks.json`, plus `handoff_complete.sql`. The synthetic task requires discovering the release
+conversation, reading its thread/checklist, posting the intended reply and adding
+the correct reaction. The verifier checks the bound actor and exact target, preserves
+baseline observations and rejects unrelated extra rows. A no-op scores zero; the
+included discovery/read/write oracle scores one. Reset restores the baseline. A live
+capture lacking an eligible root reports the scenario unavailable rather than
+inventing one. Refresh regenerates the scenario against its newly validated state.
+
+`schema/_slack_scenario.py` generates one read-only VALUES relation per populated
+entity and bounded EXCEPT/count comparisons. SQL expression depth does not grow
+with one predicate per baseline row. The grader checks exact baseline payloads,
+the intended reply and acknowledgement, and their expected counter changes; edits,
+deletions and extra rows cannot satisfy preservation by matching counts alone.
+Synthetic tests exercise actual materialized worlds with 2,048 and 9,056 records,
+including oracle/reset/reopen and refresh of an isolated copy without changing the
+original version. See `tests/environment/test_schema_slack_scale.py`; these checks
+establish local execution, not live Slack fidelity.