@wenathlan/saddle 1.8.11 → 1.8.13

package/docs/repo-research-1.8.21.md

@@ -0,0 +1,38 @@
+# Comparative repository research for 1.8.21
+
+This document records repository evidence as it is inspected. The uploaded scope README remains unchanged and is treated as an objective reference rather than an execution recipe.
+
+## Initial verified findings
+
+| Repository | Relevant capability | Evidence and possible Saddle lesson | License or boundary |
+|---|---|---|---|
+| [browser-use/browser-use](https://github.com/browser-use/browser-use) | Agent browser, custom tools, authentication profiles, persistent filesystem and memory | The public project separates a reusable agent library from hosted browser infrastructure, exposes custom tools, and documents explicit session/authentication handling. Saddle should preserve the same separation: the engine owns contracts and adapters, while browser, credentials, proxy and hosted execution remain caller-owned. | README states MIT for the open-source library; hosted cloud is a separate service and must not be copied as an implicit dependency. |
+| [SeleniumHQ/selenium](https://github.com/SeleniumHQ/selenium) | Multi-language browser automation and driver boundary | The repository presents browser automation as a framework plus ecosystem, suggesting that Saddle's browser surface should keep transport and browser-driver concerns behind replaceable adapters rather than embedding one browser provider. | Public repository; license details must be checked from the repository before reusing code or patterns. |
+| [scrapy/scrapy](https://github.com/scrapy/scrapy) | Structured web scraping and crawler extensibility | The public README describes a cross-platform framework for extracting structured data and directs contributors to dedicated documentation and contribution guidance. Saddle should continue separating crawl scheduling, extraction, normalization, storage and caller-owned transport rather than placing all behavior in one scraper function. | Public repository maintained by Zyte and contributors; exact license must be recorded from its repository metadata before any code-level comparison. |
+
+These findings are architectural observations, not copied code. Any implementation selected for Saddle must be independently authored, compatible with GPL-3.0-only, and validated against Saddle's root-first, transport-neutral and caller-owned infrastructure constraints.
+
+## Browser and crawler findings
+
+| Repository | Relevant capability | Evidence and possible Saddle lesson | License or boundary |
+|---|---|---|---|
+| [browserbase/stagehand](https://github.com/browserbase/stagehand) | TypeScript browser agents, `act`, `observe`, `extract`, self-healing actions, token-efficient page context and batch commands | Stagehand combines deterministic Playwright-style locators with agent-oriented actions and structured extraction. The useful independent lesson for Saddle is to keep natural-language observation separate from deterministic execution and to expose bounded, inspectable context rather than sending an entire page to every action. | README states MIT; Browserbase credentials and hosted browser infrastructure are explicit external dependencies, not part of the SDK contract. |
+| [apify/crawlee](https://github.com/apify/crawlee) | TypeScript/JavaScript crawling, persistent request queues, pluggable storage, proxy/session management, retries and HTTP plus browser crawlers | Crawlee separates request queue, dataset/file storage, crawler engines and routing. It supports Playwright, Puppeteer, Cheerio, JSDOM and raw HTTP behind a common crawler surface. Saddle should compare these boundaries with its existing crawl, scrape, storage and memory modules, especially around durable request queues and pluggable storage. | README states Apache-2.0; Apify cloud is optional and separate from the open-source library. |
+
+| [minio/minio](https://github.com/minio/minio) | S3-compatible object storage, multi-architecture builds and operational deployment | MinIO exposes the S3 compatibility boundary as a storage server and documents architecture-specific source builds. Saddle should remain a client/adapter contract rather than embedding an object store, and should keep endpoint, credentials, deployment and architecture decisions caller-owned. | The repository is archived and its README states GNU AGPLv3; no code should be copied into GPL-3.0-only Saddle without a separate compatibility and legal review. |
+| [temporalio/sdk-typescript](https://github.com/temporalio/sdk-typescript) | Durable workflows, activities, workers, retries and TypeScript runtime contracts | Temporal separates client, worker, workflow, activity, testing and bridge packages in a monorepo. Its README explicitly distinguishes client-level portability from worker features that depend on Node-specific APIs. Saddle should document similar runtime boundaries and avoid claiming browser/worker support for Node-only persistence or execution features. | README states MIT; the worker SDK relies on Node APIs and native modules, which is a useful warning for Saddle's transport-neutral export graph. |
+
+## Additional verified findings for the 60 repository matrix
+
+| Repository | Relevant capability | Evidence and possible Saddle lesson | License or boundary |
+|---|---|---|---|
+| [puppeteer/puppeteer](https://github.com/puppeteer/puppeteer) | Browser control, CDP transport, lifecycle and downloads | Puppeteer keeps browser process control and protocol transport behind a Node library surface. Saddle should keep browser ownership in injected adapters and avoid treating Chromium as an implicit runtime dependency. | Apache-2.0; browser binaries and Node runtime are operational dependencies rather than Saddle-owned infrastructure. |
+| [n8n-io/n8n](https://github.com/n8n-io/n8n) | Workflow nodes, executions, credentials and user-configured integrations | n8n organizes automation around explicit nodes and execution state. Its repository metadata reports `NOASSERTION`, so it is useful for architecture comparison but not for license-derived reuse. | License status requires repository-specific review; no code is copied. |
+| [dagster-io/dagster](https://github.com/dagster-io/dagster) | Asset-oriented orchestration, run state, retries and observability | Dagster makes assets, runs and execution boundaries explicit. Saddle can use the same separation to keep workflow state inspectable without coupling the core to an orchestrator service. | Apache-2.0; cloud features are separate from the core project. |
+| [prefecthq/prefect](https://github.com/PrefectHQ/prefect) | Flow runs, task retries, state transitions and worker execution | Prefect's flow and task boundary supports a caller-owned worker model. Saddle's workflow transition contract can expose cancellation, retry and compensation without owning the worker process. | Apache-2.0; hosted control plane is not part of the independent design. |
+| [apache/airflow](https://github.com/apache/airflow) | DAG scheduling, task instances, retry policy and executor adapters | Airflow separates DAG definition from task execution and executor selection. Saddle should retain the same distinction between declarative workflow manifests and the caller-selected runtime. | Apache-2.0; provider packages and deployment systems expand the operational boundary. |
+| [restic/restic](https://github.com/restic/restic) | Content-addressed backups, snapshots, retention and repository pruning | Restic models immutable snapshots and explicit retention/prune operations. Saddle can use a similar explicit retention decision for release artifacts without deleting caller data implicitly. | BSD-2-Clause; repository storage and credentials remain caller-owned. |
+| [rclone/rclone](https://github.com/rclone/rclone) | Multi-backend storage abstraction, checksums, transfers and configuration | Rclone demonstrates a broad backend adapter boundary and explicit transfer controls. Saddle should keep adapters narrow and avoid making a single object store the canonical implementation. | MIT; backend credentials and provider terms remain external. |
+| [goreleaser/goreleaser](https://github.com/goreleaser/goreleaser) | Declarative release pipelines, matrix artifacts, checksums and archives | GoReleaser makes artifact naming, archives, checksums and publisher configuration declarative. Saddle's existing release matrix can add the same deterministic metadata discipline without copying tooling code. | MIT; signing and publishing credentials are caller-owned. |
+| [sigstore/cosign](https://github.com/sigstore/cosign) | Keyless signing, attestations, transparency and artifact verification | Cosign illustrates a separation between artifact identity, signature evidence and registry storage. Saddle should report signing evidence explicitly and never turn unsigned output into a trust claim. | Apache-2.0; trust-root and identity-provider configuration are external policy choices. |
+| [renovatebot/renovate](https://github.com/renovatebot/renovate) | Dependency discovery, update planning, grouping and guarded automation | Renovate groups related updates and separates discovery from application. Saddle can use the same pattern for release and dependency planning while keeping all writes caller-authorized. | AGPL-3.0; no source reuse is required for the proposed feature. |