5pm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d607b0dac482d750b2ad2477f3265aa944ce21e1742c6c564dd698cf83c2e11
+  data.tar.gz: f9f54064b2b684aa0255dad732b6a84017e829847df9caa65d14acb0cc910a6a
+SHA512:
+  metadata.gz: 15dc1d3ef35febd811b62a9539b3da45cc99175648b780c75b3fb7e6c24b207260cad0fe85bd3498ae9ac553dfafba168ee862a37053f62db93e02f6925c3075
+  data.tar.gz: 28c70a2fe3f5f8326960cf74e8f126c0783cf091dfb40c8852eb7451eb73e4b6d6bc8faa88ce76e9305c115a3022cdc53fbe2cb527578f023700235884fe1197

data/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.1.0 — 2026-10-30
+
+- Make live API validation optional and owner-controlled. Releases no longer require
+  an active 5PM account or fresh live evidence; cached reports never expire or force
+  a refresh after source changes. Offline tests and artifact checks remain required.
+
+- Restrict releases to manual dispatch from master for an explicitly approved
+  version and exact commit; retain protected environment approval for tag/publish jobs.
+
+- Align packaging/release bin scripts with abbu and printavo: shared Bash runner,
+  Ruby support helpers, pkg artifacts, isolated installs and read-only tag verification.
+
+- Name the packages `5pm` and `5pm-mcp`, with matching dependencies, builds and
+  release configuration; retain the `FivePM` Ruby namespace and require paths.
+
+- Prepare protected GitHub OIDC publishing for both gems, with exact-commit release
+  checks, separate tag permissions, and standard Bundler build/release tasks.
+
+- Retain live cleanup ledger entries until deletion is confirmed; reject false/null/zero
+  results and independently verify absence when lookup errors use a generic API code.
+
+- Recognize mapped response parts in presence checks, verify attachment absence after
+  deletion, and bound live subprocess exit and pipe draining with process-group cleanup.
+
+- Validate UTF-8 JSON after streamed chunks are assembled; preserve arbitrary bytes
+  when probing binary downloads for API error envelopes.
+
+- Ship RBS for both gems, including all generated model readers and MCP callback
+  contracts; validate source and installed-package signatures in the default checks.
+
+- Live disposable-account contract, CRUD, pagination, MCP stdio and mutation-approval verification.
+- Redacted numeric `APIError` for HTTP-200 errors, including code 0 validation errors.
+- Preserve live integer deletion markers and add bounded binary `Download` results.
+- Opt-in reproducible live suite with separate mutation enablement and cleanup checks.
+
+- Accept live JSON booleans as well as WSDL strings for `User.canViewProfiles`,
+  preserving both representations without relaxing other string fields.
+
+- Accept the observed sign-in JSON envelope `data.sessionId`, retain the original
+  WSDL-shaped envelope, and reject ambiguous authentication responses.
+- Map operation-specific `data` envelopes in typed readers, pagination and MCP,
+  preserving raw wire JSON and false scalar results without replaying mutations.
+
+- Initial SDK scaffold, contract inventory, POST transport and synchronized sessions.
+- Generic service calls validated against public demo WSDL POST bindings.
+- CRUD/list helpers for all five resource services, synthetic RSpec contracts, CI and packaging.
+- Opt-in immutable typed responses for all schema response types, with lossless raw JSON,
+  snake_case readers, nested typed lists and strict scalar normalization.
+- Synthetic JSON fixtures and schema parity tests; live envelope verification remains pending.
+
+- Bounded opt-in read retries and pagination; streamed response-size limits and specific HTTP errors.
+- Pre-I/O request validation, rejected-session invalidation and copied credentials.
+- Explicit user/authentication/attachment helpers and typed-model request round trips.
+- Fix Enumerable overriding typed list `to_h`.
+- Isolated packaging, read-only release gates and opt-in sandbox preflight.
+
+- Separate 5pm-mcp package with official MCP SDK protocol handling, default read-only
+  tools, per-request operator approval for embedded mutations and redacted audit events.
+- Real synthetic stdio/executable tests and isolated installation checks for both artifacts.
+- Host-configurable MCP tool allowlists and stdio confirmation-enforcement regression tests.
+
+- Review fixes: retain typed-list serialization in the base layer, include DNS lookup
+  in timeout handling, reject stale live-validation evidence after code changes, and
+  emit successful MCP audit outcomes only after result serialization succeeds.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stan Carver II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# 5pm
+
+Ruby SDK for 5pm API v2. MIT licensed; Ruby 3.2+.
+
+Unreleased. Disposable-account verification covers account-specific contracts, JSON
+envelopes, resource CRUD, pagination, attachments and the standalone MCP adapter.
+See [live validation](docs/live-validation.md) for scope and reproducible checks.
+Publication still requires review and explicit approval.
+
+## Development
+
+```sh
+bundle install
+bin/spec
+bin/lint
+bin/package-mcp
+```
+
+For repeatable macOS Keychain setup and cached contract/read checks, see
+[cached validation](docs/cached-validation.md) (`bin/validate --help`).
+
+## Configuration and initial API
+
+Install from this checkout with Bundler (`gem "5pm", path: "/path/to/sdk"`).
+The gem name is `5pm`; load it with `require "five_pm"` and use the `FivePM` namespace.
+Provide `FIVE_PM_HOST`, `FIVE_PM_LOGIN`, and `FIVE_PM_PASSWORD` through your environment
+or a secret manager such as Infisical; no dotenv file is needed.
+
+```ruby
+require "five_pm"
+client = FivePM::Client.new(
+  host: ENV.fetch("FIVE_PM_HOST"), # account.5pmweb.com, without scheme or path
+  login: ENV.fetch("FIVE_PM_LOGIN"),
+  password: ENV.fetch("FIVE_PM_PASSWORD"),
+  open_timeout: 5, read_timeout: 30, write_timeout: 30
+)
+response = client.tasks.list(filter: { projectId: 123 }, offset: 0, count: 20)
+# Explicit mutations, for a disposable account only:
+# client.tasks.create(name: "Example task", projectId: 123)
+# client.tasks.update(id: 456, name: "Updated task")
+# client.tasks.get(456)
+# client.tasks.delete(456)
+# Exact wire operations are also available:
+# client.users.call("getByEmail", email: "person@example.com")
+client.sign_out
+```
+
+Services: `authentication`, `projects`, `project_groups`, `tasks`, `activity`, `users`.
+CRUD resources expose `create`, `update`, `get`, `delete`, and `list`. For users and
+project groups, `list` uses `getAll` and rejects unsupported filtering/pagination options.
+Filters and other wire options retain their documented camelCase names.
+
+Responses retain their full JSON structure and unknown fields. The initial sign-in parser
+accepts `data.sessionId`, observed in the disposable test account, and the original
+WSDL-shaped `auth.sessionId` envelope. Ambiguous envelopes are rejected; resource
+response mapping is exercised by the live suite. Pagination and read retries are explicit opt-ins;
+there is no date/time conversion. Caller-supplied
+parameters retain wire names and values. Authentication refresh is synchronized with a
+30-minute TTL and 30-second margin. Authentication HTTP failures invalidate the rejected session for the next explicit call without replay.
+All calls use form-encoded HTTPS POST; redirects and environment proxies are disabled.
+Response bodies stream into a bounded buffer (5 MiB by default, configurable with `max_response_bytes`).
+
+See [API inventory](docs/api-support.md), [security policy](SECURITY.md),
+[contributing](CONTRIBUTING.md), and [MCP follow-up plan](docs/mcp-plan.md).
+
+## Typed responses (opt-in)
+
+Both gems ship RBS signatures in `sig/`. Core signatures cover the client, resources,
+models, pagination, downloads and errors; adapter signatures cover configuration,
+approval proposals and audit events. Raw/typed configuration is selected at runtime,
+so client/resource result types are unions; narrow a result to `FivePM::Response`
+before using model readers. Unknown JSON fields remain recursive JSON values.
+The MCP SDK boundary is a structural interface because that dependency has no RBS.
+`bundle exec rake signatures` validates both sets, and package checks validate the
+signatures extracted from the built artifacts. RBS is a development-only dependency.
+
+Pass `response_mode: :typed` to `FivePM::Client.new` to receive a `FivePM::Response`.
+The default `:raw` mode keeps the original Hash/Array behavior. Both resource helpers
+and generic calls honor the selected mode; `sign_in` still returns the client.
+
+```ruby
+client = FivePM::Client.new(
+  host: ENV.fetch("FIVE_PM_HOST"), login: ENV.fetch("FIVE_PM_LOGIN"),
+  password: ENV.fetch("FIVE_PM_PASSWORD"), response_mode: :typed
+)
+response = client.tasks.list(filter: { projectId: 123 }, count: 20)
+response.list.each do |task| # FivePM::Models::TaskList is Enumerable
+  puts [task.id, task.name, task.hours_done].inspect
+end
+response.list.count # server-provided page count, when present
+response.list.total # server-provided total, when present
+response.to_h       # original JSON envelope with original wire keys and values
+response.to_json    # serializes the original JSON, including unknown fields
+```
+
+Models cover every complex response type in the public demo schema: projects, tasks,
+users, project groups, activity, files, image metadata, authentication tokens, and lists.
+Readers use snake_case (`project_id`, `first_name`); `[]` uses original wire keys
+(`task["projectId"]`). Unknown fields remain available through `[]` and `to_h`.
+Nested lists map their `items` to the appropriate model. `count` and `total` are
+metadata, not automatic pagination or a guarantee of complete results.
+
+Schema integers and finite floats accept JSON numbers or decimal strings. Schema
+booleans accept JSON booleans, integer 0/1, and strings `false`/`true`/`0`/`1`.
+String fields remain strings even if they look numeric or boolean. All date/time
+fields remain exact strings; no zone is inferred and no date parsing is attempted.
+Exception: `User.canViewProfiles` accepts both WSDL-declared strings and JSON booleans
+observed in the test account; its reader preserves either representation unchanged.
+Missing readers return nil; `key?` distinguishes missing fields from explicit null.
+For responses with a `data` wrapper, `key?` recognizes mapped reader parts as well
+as original keys; `raw.key?` checks only the wire envelope.
+Malformed known types raise `FivePM::ProtocolError` without including field values;
+these errors never trigger a replay of the request. Unknown fields are not validated.
+
+Models and their JSON snapshots are immutable and do not freeze or mutate the caller's
+input. `to_h`/`raw` return a frozen snapshot with original scalar values; typed readers
+may return normalized values. Inspection omits all payloads, including unknown fields.
+Serialization deliberately includes the complete payload, which can contain secrets.
+
+Typed readers support both WSDL response part names and JSON `data` wrappers.
+For example, `{"data":{"id":"7"}}` for getAuthorizedUser maps to `response.user`,
+and a list operation's `data` maps to `response.list`. Scalar results, including false,
+map to the operation's declared part. `to_h`/`raw`/`to_json` retain the original wire
+envelope; raw client mode also stays unchanged. Ambiguous wrappers and error-marked
+data wrappers raise `ProtocolError`. Users' optional top-level `sessionId` remains
+separate from the list data. Pagination and MCP use the same envelope mapping.
+
+The `data` wrapper is covered by synthetic regressions and live operation checks. List models continue to
+require the XSD `items`/`count`/`total` structure; no singleton or flat-array conversion
+is inferred.
+
+## Bounded pagination, retries and attachments
+
+`tasks`, `projects` and `activity` expose lazy `each_page` and `each_item` enumerators:
+
+```ruby
+client.tasks.each_item(filter: { projectId: 123 }, count: 100, max_pages: 20).take(150)
+```
+
+Enumerators request pages only as consumed, advance offset by received item count,
+and stop on empty or short pages. They reject oversized/repeated pages, incompatible
+`list.items` shapes and exhausted `max_pages` bounds rather than silently truncating.
+They do not rely on totals, assume a stable dataset, or guarantee a consistent snapshot
+while account data changes. Bounded offset pagination is exercised in live checks.
+
+`read_retries: 0` (default) disables application retries. Set 1–3 to enable retries only
+for the explicit read allowlist in `FivePM::RetryPolicy::READS`. Authentication sign-in,
+all mutations and unknown operations are excluded, even after timeouts. Transient HTTP
+429/500/502/503/504 and network errors use bounded jittered exponential backoff.
+`max_retry_delay: 30` bounds each pause. Numeric Retry-After is honored; longer than
+allowed delays, malformed values and HTTP-date headers are surfaced without retry.
+There is no automatic replay after authentication or JSON/protocol failures.
+
+HTTP errors expose numeric `status`; `RateLimitError` also exposes `retry_after` and
+`retryable?`. `NotFoundError` and `ServerError` specialize `HTTPError`. Remote error
+bodies are never included in exceptions. HTTP-200 numeric `code`/`message` error
+envelopes raise `APIError` with numeric `code`, including code 0 validation failures.
+Remote messages are discarded. These API errors never cause automatic retries.
+Deletion `status` readers preserve nonnegative integer markers as well as booleans;
+live project/task deletes return integer markers, whose meaning is not inferred.
+
+`authentication.authorized_user`, `users.find_by_email(email)`, and activity's `files`,
+`attach_files(activity_id:, files:)`, `delete_file(id)` and `download_file(id)` wrap
+verified POST bindings. Attachments preserve the WSDL FileList representation.
+Live upload verification uses `files: { "items" => [{ "name" => "example.txt",
+"type" => "file", "content" => [bytes].pack("m0"), "size" => bytes.bytesize }] }`:
+the caller supplies base64 content explicitly. Downloads return a `FivePM::Download`
+in both response modes, with immutable binary `bytes`, optional `content_type`, and
+redacted inspection. They use the authenticated POST endpoint, share the HTTP response
+size limit, and never follow returned URLs. The live endpoint returns bytes despite
+the JSON option. Missing-file API error envelopes are raised rather than returned as files.
+
+User creation requires a symbolic `securityLevel` such as `"user"` in the tested
+account, even though returned records use numeric strings and the help reference
+lists numeric role codes. Request values are not silently translated.
+
+Request validation rejects missing required operation parameters, unsafe nested field
+names, arbitrary Ruby objects, cycles, invalid identifiers and invalid pagination bounds
+before authentication or I/O. Typed records can be passed to create/update helpers using
+their original JSON fields. Model list `to_h` retains the JSON view despite Enumerable.
+Clients copy configuration strings and refuse Marshal serialization of credentials.
+
+Run `bin/package` to verify the actual built artifact. See
+[release preparation](docs/releasing.md) and [implementation guideposts](docs/implementation-guides.md).
+
+## Remaining release gates
+
+- Review and merge the offline-tested source; live API refreshes are optional and owner-controlled.
+- Keep the supported Ruby matrix passing in hosted CI. Live checks remain opt-in and outside CI.
+- Date/time strings remain opaque; no timezone conversion or consistent-snapshot guarantee is offered.
+- Rate-limit and transient-network behavior is tested synthetically, without stressing the live account.
+- Configure the protected `release` environment and both RubyGems trusted publishers
+  using [release preparation](docs/releasing.md); verify name availability and obtain
+  explicit approval for the version and exact commit before dispatching publication.
+
+Official sources: [developer guide](https://www.5pmweb.com/5pm_api.php),
+[API reference](https://www.5pmweb.com/help/api_docs.php).
+
+## Standalone MCP adapter
+
+The separate [5pm-mcp package](mcp/README.md) provides ten read tools over the
+SDK using the official MCP Ruby SDK. Its executable is read-only; optional embedded
+project/task mutation tools require trusted per-call operator approval. MCP is a
+runtime dependency only of that separate gem. Run `bundle exec five-pm-mcp` with
+the same injected environment variables, or see its README for host configuration.
+
+`bin/package-mcp` verifies both installed artifacts and the adapter
+protocol in an isolated temporary GEM_HOME. `bin/live-check` adds opt-in disposable
+account verification; no gem publication is automated.

data/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+Report vulnerabilities privately through GitHub private vulnerability reporting when enabled.
+Do not put credentials or private account data into public issues.
+
+The client uses HTTPS POST bodies, peer certificate verification, fixed account hostnames,
+public IPv4 resolution pinned per connection, bounded timeouts, and no proxies or redirects.
+Read retries are disabled by default and bounded by an explicit read-operation allowlist
+when enabled. Authentication, mutations, API errors and schema failures are never replayed.
+Sessions are held only in memory. Attachment downloads use the same bounded authenticated
+transport; their inspection and MCP audit events never include binary contents.
+Client and transport inspection redact state; callers must also avoid logging request bodies
+or returned user records. Ruby memory is not a secure secret vault.
+
+No Rails application is present; Brakeman does not apply.

data/docs/api-support.md

@@ -0,0 +1,71 @@
+# API v2 contract inventory
+
+Source: public demo account WSDLs fetched over HTTPS on 2026-10-28.
+
+These are upstream contracts, not response recordings. The account-specific WSDL/XSD
+inventories were compared successfully on 2026-10-30. See [live validation](live-validation.md)
+for JSON-envelope differences and sanitized regression fixtures.
+
+| Service | Operation | POST request parts | Response parts |
+| --- | --- | --- | --- |
+| activity | add | sessionId: `xsd:string`, activity: `nsc:Activity` | activity: `nsc:Activity` |
+| activity | update | sessionId: `xsd:string`, activity: `nsc:Activity` | activity: `nsc:Activity` |
+| activity | remove | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| activity | getList | sessionId: `xsd:string`, filter: `nsc:ActivityListFilter`, offset: `xsd:integer`, count: `xsd:integer`, withFiles: `xsd:boolean`, withNames: `xsd:boolean` | list: `nsc:ActivityList` |
+| activity | getFilesList | sessionId: `xsd:string`, filter: `nsc:ActivityListFilter`, offset: `xsd:integer`, count: `xsd:integer` | list: `nsc:FileList` |
+| activity | getById | sessionId: `xsd:string`, id: `xsd:integer`, withNames: `xsd:boolean` | activity: `nsc:Activity` |
+| activity | attachFiles | sessionId: `xsd:string`, activityId: `xsd:integer`, files: `nsc:FileList` | status: `xsd:boolean` |
+| activity | removeFile | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| activity | downloadFile | sessionId: `xsd:string`, id: `xsd:integer`, stream: `xsd:boolean` | file: `nsc:File` |
+| activity | getResizeImg | Declared message only; no POST binding | Unsupported |
+| authentication | signIn | login: `xsd:string`, password: `xsd:string` | auth: `nsc:AuthToken` |
+| authentication | signOut | sessionId: `xsd:string` | signOutState: `xsd:boolean` |
+| authentication | getAuthorizedUser | sessionId: `xsd:string` | user: `nsc:User` |
+| authentication | nop | sessionId: `xsd:string` | nopState: `xsd:boolean` |
+| authentication | isSsl |  | isSsl: `xsd:boolean` |
+| projects | add | sessionId: `xsd:string`, project: `nsc:Project` | project: `nsc:Project` |
+| projects | update | sessionId: `xsd:string`, project: `nsc:Project` | project: `nsc:Project` |
+| projects | remove | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| projects | getById | sessionId: `xsd:string`, id: `xsd:integer` | project: `nsc:Project` |
+| projects | getAll | sessionId: `xsd:string`, loadTeam: `xsd:boolean` | list: `nsc:ProjectList` |
+| projects | getList | sessionId: `xsd:string`, filter: `nsc:ProjectListFilter`, offset: `xsd:integer`, count: `xsd:integer`, loadTeam: `xsd:boolean` | list: `nsc:ProjectList` |
+| projectsgroups | add | sessionId: `xsd:string`, group: `nsc:ProjectsGroup` | group: `nsc:ProjectsGroup` |
+| projectsgroups | update | sessionId: `xsd:string`, group: `nsc:ProjectsGroup` | group: `nsc:ProjectsGroup` |
+| projectsgroups | remove | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| projectsgroups | getById | sessionId: `xsd:string`, id: `xsd:integer` | group: `nsc:ProjectsGroup` |
+| projectsgroups | getAll | sessionId: `xsd:string` | list: `nsc:ProjectsGroupList` |
+| tasks | add | sessionId: `xsd:string`, task: `nsc:Task` | task: `nsc:Task` |
+| tasks | update | sessionId: `xsd:string`, task: `nsc:Task` | task: `nsc:Task` |
+| tasks | remove | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| tasks | getById | sessionId: `xsd:string`, id: `xsd:integer` | task: `nsc:Task` |
+| tasks | getList | sessionId: `xsd:string`, filter: `nsc:TaskListFilter`, offset: `xsd:integer`, count: `xsd:integer`, loadTeam: `xsd:boolean` | list: `nsc:TaskList` |
+| users | add | sessionId: `xsd:string`, user: `nsc:User` | user: `nsc:User` |
+| users | update | sessionId: `xsd:string`, user: `nsc:User` | user: `nsc:User` |
+| users | remove | sessionId: `xsd:string`, id: `xsd:integer` | status: `xsd:boolean` |
+| users | getById | sessionId: `xsd:string`, id: `xsd:integer` | user: `nsc:User` |
+| users | getByEmail | sessionId: `xsd:string`, email: `xsd:string` | user: `nsc:User` |
+| users | getAll | sessionId: `xsd:string` | sessionId: `xsd:string`, list: `nsc:UserList` |
+| users | getAuthorizedUser | sessionId: `xsd:string` | user: `nsc:User` |
+
+## Known discrepancies and limits
+
+- Activity getResizeImg has request/response messages but no POST binding; it is deliberately excluded from callable operations.
+- The schema declares AuthToken twice; do not assume strict XSD validation succeeds.
+- Help reference contains GET/POST path inconsistencies. Use WSDL POST bindings.
+- Activity getList help text calls its result GroupList; WSDL declares ActivityList.
+- Users getAll declares sessionId alongside list in its response. Preserve the whole response.
+- HTTP-200 numeric API errors, data wrappers and binary downloads are covered by live checks.
+- Pagination and read retries are bounded opt-ins. There is no date/time conversion or URL fetching.
+- No credentials were used to fetch these contracts.
+
+Sources: https://www.5pmweb.com/5pm_api.php and https://www.5pmweb.com/help/api_docs.php
+
+## Snapshot checksums
+
+- `activity.wsdl`: `381ef30b11b407778e9d899b4aa77b4d8b53b99d116fafd515f1f5ea33753fcc`
+- `authentication.wsdl`: `e5e408bd08ad40f1daa0d65038975aa2e8230a39d0ba25f126995a5173ace132`
+- `projects.wsdl`: `4686919f3a5ec647a5d9ed067e2c85bd93065ea43a25bae52326e37582975486`
+- `projectsgroups.wsdl`: `ade39f53b9be0aa081221a7dbc1fe63bdd7317e6c3c1e8bdca4dfa993c852604`
+- `schema.xsd`: `aa938cd35e979479b3559bbd04327fc9d91c3ce5ac860635e4465aa2a65827a8`
+- `tasks.wsdl`: `d8cabc28841b33515f9c23ab5d1ca9f5975b486f173c98bcde5026f05a59480f`
+- `users.wsdl`: `a660022447f04d7c32e92768eb77e8e6568b56bc775bd9f3c66152b1227d9bdc`

data/docs/cached-validation.md

@@ -0,0 +1,58 @@
+<!-- docs/cached-validation.md -->
+# Keychain and cached validation
+
+Run these commands from the checkout on macOS. The setup prompts for the disposable
+tenant's hostname (without scheme/path), standard User login, and password. Each is
+stored in the login Keychain under `5pm-ruby.validation.host`, `.login`, or `.password`,
+with account `5pm-ruby`. Keychain may ask for access permission. Values never appear
+in command arguments, repository files, output, or the cached report.
+
+```sh
+bin/validate --setup
+```
+
+Commit the reviewed source changes before validating. On the first run, explicitly
+designate the tenant as disposable. This runs the existing read-only live harness,
+including WSDL/XSD contract checks and session cleanup. It does not run CRUD tests.
+
+```sh
+bin/validate --disposable
+```
+
+Later runs reuse the cached evidence without Keychain access or network requests.
+There is no timer, polling, expiration, or automatic refresh:
+
+```sh
+bin/validate
+```
+
+After a known 5PM API update, deliberately replace the cache:
+
+```sh
+bin/validate --refresh --disposable
+```
+
+Changes to SDK code, adapter code, bin commands or validation helpers set
+`source_matches: false` on a cached result. The old report remains usable as
+historical evidence, with its original commit and fingerprint. Source changes never
+force a live refresh. Failed refreshes preserve the previous file. Updating
+credentials does not refresh evidence.
+Use a distinct `--service NAME` per tenant; that also selects a separate default cache.
+
+The default cache is `~/Library/Caches/5pm-ruby/<service-sha256>.json`, outside the
+repository, with mode 0600. `--cache FILE` selects a different local destination.
+It stores only the validation timestamp, tested commit, source fingerprint and scope.
+It excludes remote responses, tenant details, tokens, credentials and record IDs.
+
+Cached contract/read evidence has `release_evidence: false` and
+`mutations_verified: false`. It is reusable development evidence, not fabricated
+a fresh validation of changed source. Live evidence is optional for releases:
+Stan decides when a refresh is needed. No active account or subscription is required
+to run offline tests, package checks or release preflight.
+
+See [live validation](live-validation.md) and [release preparation](releasing.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/implementation-guides.md

@@ -0,0 +1,12 @@
+# Implementation guideposts
+
+Reviewed these user-owned repositories as design guides, without importing their
+service-specific behavior or adding their dependencies to the SDK:
+
+- [printavo-ruby client](https://github.com/scarver2/printavo-ruby/blob/464ae6f29b8ff7627cf829c02351d1b9eadea37d/lib/printavo/client.rb): independent clients, resource helpers, explicit configuration.
+- [printavo-ruby connection](https://github.com/scarver2/printavo-ruby/blob/464ae6f29b8ff7627cf829c02351d1b9eadea37d/lib/printavo/connection.rb): configurable retry controls; FivePM restricts retries further to an explicit read-operation allowlist.
+- [abbu packaging](https://github.com/scarver2/abbu/blob/4c64d0eb0ccdbc0a8c04b2e50da92594faf75d09/bin/package): verify the built artifact independently of its source checkout.
+- [abbu release preflight](https://github.com/scarver2/abbu/blob/4c64d0eb0ccdbc0a8c04b2e50da92594faf75d09/bin/release-check): inspect accepted commits without executing candidate code; separate preparation from publication authorization.
+- [abbu MCP adapter](https://github.com/scarver2/abbu/blob/4c64d0eb0ccdbc0a8c04b2e50da92594faf75d09/lib/abbu/mcp/server.rb): use the official SDK for protocol handling, allowlist tools and redact errors.
+
+The public 5pm WSDL/XSD remains the source for 5pm-specific operations and types.

data/docs/implementation-status.md

@@ -0,0 +1,45 @@
+# Issue #1 implementation status
+
+Initial implementation, 2026-10-28. Worktree: `sdk`, branch: `feat/api-v2-sdk`.
+
+## Implemented
+
+- MIT gem scaffold with Ruby 3.2 minimum, explicit runtime dependencies and checksum lockfile.
+- Snapshots of all six public demo service WSDLs and schema; 37 callable POST operations.
+- Complete request/response part inventory with source discrepancies documented.
+- Six services, five resource CRUD/list helpers, generic calls limited to verified POST bindings.
+- HTTPS form POST, public IPv4 pinning, fixed account domains, timeouts, no redirects/proxies and read retries disabled by default.
+- In-memory synchronized sessions with 30-minute TTL and conservative refresh margin.
+- Error classes that omit remote bodies, network details and chained secret-bearing exceptions.
+- RSpec synthetic tests, WSDL contract checks, SimpleCov 90% minimum, RuboCop, CI and Dependabot.
+- Packaging validation, quickstart, contribution/security policies and separate MCP adapter plan.
+- Opt-in typed response models for all 14 schema response types; unknown fields and raw JSON preserved.
+- Nested typed lists, immutable snapshots, snake_case readers and redacted inspection.
+
+- Bounded optional read retries/pagination, streamed body limits, request validation and explicit attachment helpers.
+- Isolated package verification, read-only release gate and opt-in read-only sandbox preflight.
+- Reviewed scarver2/abbu and scarver2/printavo-ruby patterns; see implementation-guides.md.
+
+- Separate 5pm-mcp gem with official SDK, read-only stdio tools, opt-in host-confirmed mutations and redacted audit events.
+- Real synthetic stdio/executable tests and isolated installation verification for both gem artifacts.
+
+## Verification completed on 2026-10-30
+
+- Offline schema, protocol, redaction, binary transport and mutation-safety regression tests.
+- RuboCop, strict builds, core dependency isolation and installed-package checks.
+- Live account-specific WSDL/schema comparison, all resource CRUD/read paths,
+  pagination, user creation and synthetic-attachment byte round trips.
+- Live MCP stdio reads and embedded project/task mutation approvals, denials and audits.
+- Supported Ruby matrix: 3.2, 3.3, 3.4 and 4.0.
+
+See [live validation](live-validation.md) for reproducible commands and API differences.
+The development report identifies the tested working tree; it does not authorize a release.
+
+## Remaining release gates
+
+- Review and merge the tested source with passing hosted CI.
+- Generate accepted-commit release evidence according to [releasing](releasing.md).
+- Recheck RubyGems name availability and obtain explicit publication approval.
+
+Date/time conversion is intentionally absent. Retry/rate-limit failure paths are
+verified synthetically rather than by stressing the live account.