scoutline 0.19.7 → 0.21.0

package/README.md

@@ -15,7 +15,7 @@
 
 ## Features
 
-- **Vision** - Analyze images, screenshots, diagrams, charts, videos using GLM-5V-Turbo
+- **Vision** - Analyze images, screenshots, diagrams, charts, videos using GLM-5.3-Flash
 - **Search** - Real-time web search with domain and recency filtering
 - **Reader** - Fetch and parse web pages to markdown
 - **Repo** - Search and read GitHub repository code via ZRead
@@ -23,7 +23,8 @@
 - **Code Mode** - TypeScript tool chaining for agent automation
 - **Provider selection** - Run shared capabilities through Z.AI, MiniMax, Tavily, Exa, Brave, Firecrawl, Parallel AI, Perplexity, Jina AI, You.com, Linkup, or Spider.cloud
 - **Usage ledger** - Local 90-day call-usage history per provider and capability (`scoutline usage`), counters only
-- **Saved artifacts** - Durable clean reports from any provider-backed run (`--save`), content + request id only, plus a credential-free `scoutline history` inventory (list/show/stats)
+- **Saved artifacts** - Durable clean reports from any provider-backed run (`--save`), content + request id only, plus a credential-free `scoutline history` inventory (list/show/stats/recall/export/note/clear)
+- **Research journal** - Always-on local memory of every `search`/`read`/`research` call: thin skeletons (query, provider, url+title identity, content hash) recorded under `~/.scoutline/artifacts/` and re-found offline via `history recall`; opt out per call (`--no-journal`) or globally (`journal: false`)
 
 ## Quick Start
 
@@ -80,6 +81,35 @@ imported env key will keep overriding the saved key.
 
 Run `scoutline init --help` for the full lifecycle and exit-code reference.
 
+### Agent Registration
+
+During `scoutline init`, every agent tool detected under your home directory
+(claude, opencode, codex, gemini, qwen, copilot) gets a confirm prompt
+(default yes) to register scoutline. Registering writes two things per tool:
+
+- a **thin rules file** (always loaded — identity, one-line capability
+  surface, and a pointer to the full skill), and
+- the **full agent skill** copied into that tool's native skills home.
+
+Choices persist to the additive `agentRules` config key; undetected tools
+never prompt, and a version or rule-text drift triggers a silent lazy
+refresh on the next CLI run (no re-prompt). Every shared-file mutation is
+idempotent, atomic, and byte-preserving outside the managed region.
+
+Reversal is first-class:
+
+```bash
+scoutline init --unregister
+```
+
+It removes owned rule files and skill copies, strips pointer lines, marker
+blocks, and JSON array entries in place, clears the stamp and `agentRules`
+config key, and deletes the per-file `.scoutline-bak` backups. Those
+backups are a **disaster recovery** escape hatch only — minted once on the
+first mutation of a pre-existing file so you can manually recover if an
+engine bug ever corrupts a file. Unregister never restores from them: your
+own edits to shared files are preserved byte-for-byte by region stripping.
+
 ## Installation
 
 ### As an Agent Skill
@@ -157,7 +187,7 @@ selected provider does not advertise the capability (for example,
 MiniMax does not advertise `repository-exploration` or `reader`) or
 fails at runtime, Scoutline emits a stderr notice and silently
 reroutes to the next eligible configured provider in registry order
-`[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider]`. Pass `--no-fallback`
+`[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider, arxiv, openalex, crossref, pubmed, europepmc]`. Pass `--no-fallback`
 (or set `SCOUTLINE_NO_FALLBACK=1`) to restore the previous strict
 single-provider, fail-loud behavior for scripting or cost-sensitive
 workflows. See
@@ -252,14 +282,58 @@ output is byte-identical to previous releases.
 
 Any provider-backed command (`search`, `read`, `crawl`, `map`, `research`, `repo`, `vision`) accepts `--save [<path>]`: after a successful run it writes a durable **clean report** — content plus a request id, nothing else — while stdout stays byte-identical. The master copy always lands in the artifact store (`~/.scoutline/artifacts/`, override `SCOUTLINE_ARTIFACTS_DIR`); `--save <path>` additionally writes an export copy (refused on an existing target unless `--save-force`). Reports are redacted through the same seam as stdout and never touched by `cache clear` or TTLs. `scoutline history list/show/stats` is the credential-free, fail-open inventory over the store's `index.json` metadata log, joined to reports by request id.
 
+### Research Journal (always-on, local-only)
+
+Every `search`, `read`, and `research` call — batch-driven ops included —
+appends a thin **journal entry** to the same store: query, provider,
+timestamp, a content hash, and the **skeleton** of the result (search:
+url+title list; read: url+title; research: citations). Result bodies are
+never recorded — they live in the 24h response cache or in an explicit
+`--save` artifact — and a warm repeat (cache hit) appends only a tiny
+**repeat marker**, unless the journal holds no prior full entry under
+that cache key (journal-cold, e.g. after `history clear`), in which case
+the hit records a full entry instead. Entries are self-contained forever:
+`cache clear` never
+touches them and nothing is ever re-fetched. Journaling changes no
+provider-call volume; savings come from using `history recall` instead of
+re-running searches.
+
+```bash
+scoutline history recall "rust async"              # offline re-find over skeletons
+scoutline history recall "rust" --capability search --limit 5
+scoutline history recall "state of ai" --as-of 2026-08-01   # what the journal knew then
+scoutline history note --capability search "decided on tavily for finance"  # explicit entry
+scoutline history export                            # markdown dossier, provenance-cited
+scoutline history list --kind journal               # journal entries only; --repeats shows markers
+scoutline history clear                             # clears journal entries only
+scoutline history clear --all                       # also wipes --save artifacts + masters
+```
+
+**Privacy**: the journal is local-only (`~/.scoutline/artifacts/` — the
+directory is created 0700 and the files inside 0600, never uploaded), and
+query text passes the configured-secrets redaction seam before it is written. Disclosure is one prompt in
+`scoutline init` (default: enabled, writing `"journal": true`); users who
+never run init get the enabled default too. Escape hatches: `--no-journal`
+on any single `search`/`read`/`research` call (rejected as
+`UNSUPPORTED_OPTION` everywhere else), `scoutline config set journal false`
+(or the init re-config menu) to stop entirely.
+
+Scale note: the journal shares `index.json` with `--save` and appends
+rewrite the whole log under a write lock. Measured appends stay well under
+100ms through ~20k entries; segmented-log/compaction is the named future
+policy for larger journals.
+
 ## Capability Matrix
 
 The matrix below is generated from the production provider registry
 (`packages/scoutline/src/providers/registry.ts`) and reflects the
-release-shipped capability advertisements for every built-in provider
-in registry order `[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider]`. The
-exact same `descriptor.capabilities()` set drives executor preflight,
-Provider selection, and `doctor`.
+release-shipped capability advertisements; the registry order is
+`[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider, arxiv, openalex, crossref, pubmed, europepmc]`.
+The matrix columns cover the shared-capability providers — the five
+keyless science suppliers (arXiv, OpenAlex, Crossref, PubMed, Europe
+PMC) serve only `scoutline science ...` and `doctor` (see the Science
+section). The exact same `descriptor.capabilities()` set drives
+executor preflight, Provider selection, and `doctor`.
 
 | Capability | Z.AI | MiniMax | Tavily | Exa | Brave | Firecrawl | Parallel | Perplexity | Jina | You.com | Linkup | Spider.cloud | Notes |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -277,7 +351,7 @@ Provider selection, and `doctor`.
 | `read` (Reader) | Yes | **No** | Yes | Yes | No | Yes | Yes | No | Yes | Yes | Yes | Yes | Parallel (Extract API), Jina, You.com, Linkup, and Spider.cloud add Reader support |
 | `crawl` | **No** | **No** | Yes | No | No | Yes (async) | No | No | No | No | No | Yes (sync) | Tavily sync; Firecrawl async (resumable after Ctrl-C) |
 | `map` | **No** | **No** | Yes | No | No | Yes | No | No | No | No | No | Yes | URL-set discovery; no per-page content |
-| `research` | **No** | **No** | Yes | Yes | **No** | **No** | Yes | Yes | Yes | Yes | Yes | No | Tavily, Exa, Parallel, Perplexity `sonar-deep-research`, Jina DeepSearch, You.com, and Linkup research report synthesis |
+| `research` | **No** | **No** | Yes | Yes | **No** | **No** | Yes | Yes | Yes | Yes | Yes | No | Tavily, Exa, Parallel, Perplexity (Agent API `high` preset), Jina DeepSearch, You.com, and Linkup research report synthesis |
 | `repo search` / `repo read` / `repo tree` / `repo brief` | Yes | **No** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | No | Participates in selection; only Z.AI supplies `repository-exploration` |
 | `tools`, `tool`, `call` (Raw tools) | Yes | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
 | `code` (Code Mode) | Yes | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
@@ -355,6 +429,26 @@ from the same registry, so once a mapping is promoted it appears on
 every runtime surface automatically — there is no second support list
 to update.
 
+## Science
+
+Keyless scholarly literature search and retrieval across five suppliers —
+arXiv, OpenAlex, Crossref, PubMed, and Europe PMC. No API key is required:
+the command dispatches credential-free (optional `OPENALEX_API_KEY` /
+`NCBI_API_KEY` unlock higher rate limits).
+
+```bash
+scoutline science search "graph transformers" --year 2020:2024
+scoutline science search "attention" --author Vaswani --provider crossref
+scoutline science get 10.1038/nature12373
+```
+
+`science search <query>` fans out across all five suppliers by default
+(`--provider <id>` pins one) and merges a deduplicated work list, with
+`--author`, `--year`, `--venue`, and `--type` filters consumed only where
+the supplier wire supports them (rejected with `UNSUPPORTED_OPTION`
+elsewhere — never silently dropped). `science get <identifier>` fetches
+one work by bare DOI, numeric PMID, or arXiv id.
+
 ## Usage
 
 The CLI is self-documenting. Use `--help` at any level:
@@ -368,7 +462,7 @@ scoutline doctor --help       # Provider diagnostics
 scoutline quota --help        # Plan usage
 scoutline cache --help        # Local cache inspection, clearing, and pruning
 scoutline usage --help        # Local call-usage history (usage.json ledger)
-scoutline history --help      # Saved-artifact inventory (list/show/stats)
+scoutline history --help      # Saved artifacts + research journal (list/show/stats/recall/export/note/clear)
 ```
 
 ### Examples
@@ -391,6 +485,7 @@ scoutline search "security news" --recency oneDay
 # Reader - fetch web content
 scoutline read https://docs.example.com/api
 scoutline read https://blog.example.com --format text
+scoutline read https://example.com/long-article --max-chars 2000
 
 # Repo - GitHub exploration
 scoutline repo tree facebook/react
@@ -428,6 +523,11 @@ scoutline search "rust vs go" --save --save-format markdown  # master only
 scoutline history list --limit 5                   # newest saves, from the log
 scoutline history show 20260829T142233Z-7f3a       # metadata + report, joined
 
+# Research journal - recall past work instead of re-searching (offline)
+scoutline history recall "rust async" --limit 5    # scored re-find over skeletons
+scoutline history export                          # cited markdown dossier
+scoutline search "rust async" --no-journal         # skip journaling one call
+
 # Config - inspect and change settings (scriptable, always redacted)
 scoutline config get                  # full config dump (credentials masked)
 scoutline config set routing.search tavily,brave
@@ -503,7 +603,7 @@ payload — the summary is presentation-only.
   healthy-first row ordering never changes exit codes. `--available` filters
   the `providers` array to the `availability: "ok"` rows; the
   `availableProviders` summary is unchanged by the filter.
-- `read` returns a schema-version-1 envelope (content read or extract read) in every output mode. `--with-images-summary`, `--no-gfm`, and `--keep-img-data-url` are passed through to the Provider request. `--max-chars` is ignored on extract reads; `--full-envelope` is silently deprecated.
+- `read` returns a schema-version-1 envelope (content read or extract read) in every output mode. `--with-images-summary`, `--no-gfm`, and `--keep-img-data-url` are passed through to the Provider request. `--max-chars` is a whole-envelope budget on both shapes (extract reads trim field values only); `--full-envelope` is silently deprecated.
 - Vision tool calls automatically retry transient 5xx/network errors (default: 2 retries). Configure with `ZAI_MCP_VISION_RETRY_COUNT` (or `ZAI_MCP_RETRY_COUNT` for all tools).
 - Tool discovery can be cached to speed `tools`/`tool`/`doctor` (default: on, 24h TTL). The cache shares the unified root with the response cache; configure both via `SCOUTLINE_CACHE`, `SCOUTLINE_CACHE_TTL_MS`, `SCOUTLINE_CACHE_SIZE_MB`, and `SCOUTLINE_CACHE_DIR` (legacy aliases `ZAI_MCP_TOOL_CACHE*`, `ZAI_MCP_CACHE_DIR`, and `ZAI_CACHE*` are accepted silently).
 - The local cache lives at `~/.scoutline/` (`cache/` for responses, `tools/` for tool discovery) on every platform. Inspect, clear, or prune it with `scoutline cache stats`, `scoutline cache clear`, and `scoutline cache prune`. Prune deletes expired entries by their stored timestamp (`--older-than <24h|90m|30s|seconds>` replaces the TTL threshold; `--provider`/`--capability` narrow the response scan to v2 filenames — the tool cache is unpartitioned and is always scanned age-only).
@@ -553,21 +653,26 @@ legacy grammar; it is not wrapped in the v1 envelope.
 - Actual `.`/`..` segments, backslashes, and ASCII control characters are
   rejected. Percent escapes (`%XX`) are never decoded — they remain literal.
 
-### `--max-chars` (deterministic, local)
+### `--max-chars` (Output Budget, deterministic and local)
 
 `--max-chars` is **never** a summarization model call. It is presentation
-projection applied to the normalized result after caching.
-
-- Absent, zero, or negative → no truncation.
-- `repo read` → truncates `content` with the existing ellipsis rule; preserves
-  the original length in `originalContentLength` and sets `truncated: true`.
-- `repo search` → applies **one total budget** across `excerpts[].text` in
-  Provider order; the final retained excerpt is truncated and later excerpts
-  are omitted.
-- `repo tree` → never character-limited.
-- `repo brief` → forwarded verbatim to every search and read call (per-call
-  budget); the tree probe is never character-limited.
-- Metadata, JSON envelopes, and Tree snapshots are not part of the budget.
+projection applied to the normalized result after caching: "fit everything
+this command prints in ~N characters" (ADR-0007).
+
+- Absent, zero, or negative → no budget.
+- `repo read` → whole-envelope budget; `content` trims and later sections
+  drop late, repository/path never cut; preserves the original length in
+  `originalContentLength` and sets `truncated: true`.
+- `repo search` → whole-envelope budget; excerpts trim, trailing excerpts
+  drop; URLs are never cut.
+- `repo tree` → **rejects** the flag (`UNSUPPORTED_OPTION`).
+- `repo brief` → applied **once** to the assembled brief envelope (never
+  forwarded per-probe); README excerpts and file bodies trim, file inventory
+  drops late, repository name and structure summary never cut.
+- When the budget fires, the payload gains a `compaction` field and the full
+  untrimmed envelope is saved to the artifacts store — recover with
+  `scoutline history show <ref>`.
+- Metadata and JSON envelopes are never part of the ladder's cut order.
 
 ### Empty results
 
@@ -681,8 +786,9 @@ always structured data.
 **Scripting impact:** any consumer that did `scoutline read URL > file.md`,
 `scoutline read URL | jq -r .content`, or `scoutline read URL --extract code |
 jq -c .[]` against v0.2 output must switch to the v1 envelope. `--max-chars`
-still truncates the content-read `content`; it is **ignored on extract reads**
-(extract reports `originalItemCount` instead). The deprecated
+is a whole-envelope Output Budget on both shapes; on extract reads it trims
+field values only (never drops field names or URLs; extract reports
+`originalItemCount`). The deprecated
 `--full-envelope` flag is silently accepted and ignored — the envelope is
 always returned at v1.
 

package/dist/capabilities/map.d.ts

@@ -10,9 +10,9 @@
  * selection, retries, or presentation.
  *
  * Map is the simplest of the three new Tavily capabilities: the API
- * returns URLs only (no per-page content), so there is no per-page
- * projection or truncation concern. The handler therefore needs no
- * `--max-chars` flag.
+ * returns URLs only (no per-page content), so Map is not an Output
+ * Budget ladder surface — the dispatcher rejects `--max-chars` there
+ * (UNSUPPORTED_OPTION).
  */
 import type { CacheIdentity, CachedOperation } from "../lib/execution.js";
 /**

package/dist/capabilities/map.js

@@ -10,9 +10,9 @@
  * selection, retries, or presentation.
  *
  * Map is the simplest of the three new Tavily capabilities: the API
- * returns URLs only (no per-page content), so there is no per-page
- * projection or truncation concern. The handler therefore needs no
- * `--max-chars` flag.
+ * returns URLs only (no per-page content), so Map is not an Output
+ * Budget ladder surface — the dispatcher rejects `--max-chars` there
+ * (UNSUPPORTED_OPTION).
  */
 // ===========================================================================
 // Total normalized cache decoder

package/dist/capabilities/quota.d.ts

@@ -22,6 +22,11 @@
  *     `used` alongside the explicit percentage; `limit` and `remaining`
  *     are omitted rather than fabricated. Additive under QuotaDashboard
  *     schema v1.
+ *   - A Provider whose counts are invalid but which publishes an exact
+ *     `remaining` (e.g. Z.AI's cumulative `currentValue` past the
+ *     window cap — GitHub #109) has `remaining` published verbatim next
+ *     to any explicit remaining percentage; counts are omitted rather
+ *     than derived from contradicting fields.
  *   - Invalid optional counts are omitted together (not set to zero).
  *   - A category that has neither a valid percentage, nor valid counts,
  *     nor an explicit remaining is rejected with `QUOTA_ERROR`.
@@ -168,12 +173,14 @@ export interface QuotaWindowInputs {
      */
     explicitRemainingPercent?: number;
     /**
-     * A Provider-supplied EXACT remaining count for a window whose limit
-     * is unknown (GitHub #49). Used only when neither an explicit
-     * percentage nor a valid count set is present: the built window
-     * carries `remaining` verbatim and omits `used`, `limit`, and
-     * `remainingPercent` — nothing is inferred from tier tables or
-     * fabricated as a percentage.
+     * A Provider-supplied EXACT remaining count. Two distinct uses:
+     * (GitHub #49) a window whose limit is unknown and neither an
+     * explicit percentage nor a valid count set is present — the built
+     * window carries `remaining` verbatim and omits `used`, `limit`, and
+     * `remainingPercent`; and (GitHub #109) a window whose counts are
+     * invalid — `remaining` is published verbatim next to any explicit
+     * remaining percentage, counts omitted. Nothing is ever inferred
+     * from tier tables or fabricated as a percentage.
      */
     remaining?: number;
 }

package/dist/capabilities/quota.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/capabilities/quota.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/capabilities/quota.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/quota.js

@@ -22,6 +22,11 @@
  *     `used` alongside the explicit percentage; `limit` and `remaining`
  *     are omitted rather than fabricated. Additive under QuotaDashboard
  *     schema v1.
+ *   - A Provider whose counts are invalid but which publishes an exact
+ *     `remaining` (e.g. Z.AI's cumulative `currentValue` past the
+ *     window cap — GitHub #109) has `remaining` published verbatim next
+ *     to any explicit remaining percentage; counts are omitted rather
+ *     than derived from contradicting fields.
  *   - Invalid optional counts are omitted together (not set to zero).
  *   - A category that has neither a valid percentage, nor valid counts,
  *     nor an explicit remaining is rejected with `QUOTA_ERROR`.
@@ -145,6 +150,16 @@ export function buildQuotaWindow(inputs) {
         // count) before #99.
         window.used = inputs.used;
     }
+    else if (typeof inputs.remaining === "number" &&
+        Number.isFinite(inputs.remaining) &&
+        inputs.remaining >= 0) {
+        // Invalid counts but a Provider-published EXACT remaining count
+        // (e.g. Z.AI cumulative currentValue > cap): publish `remaining`
+        // verbatim next to any explicit percentage; never derive counts.
+        // Ordered after the #99 used-only path so every pre-existing
+        // accepting input keeps its exact pre-#109 shape.
+        window.remaining = inputs.remaining;
+    }
     if (isFinitePositive(inputs.durationSeconds)) {
         window.durationSeconds = inputs.durationSeconds;
     }

package/dist/capabilities/quota.js.map

@@ -1 +1 @@
-{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/capabilities/quota.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/capabilities/quota.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/science.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Science Capability Contract (DESIGN D1; PRD AC-10d).
+ *
+ * One capability file, house shape mirroring `search.ts`. Declares the
+ * Provider-neutral meaning shared by every science supplier: the control
+ * record, search/get request shapes, the normalized `ScienceWork` result,
+ * the supplier-partitioned cache identity, and the three capability
+ * interfaces (search/get/cite). This ticket ships ONLY the contract — no
+ * Provider, transport, or Adapter code lives here.
+ *
+ * Interfaces are compile-time only, so the validate() grammars are
+ * implemented as exported pure helpers (`validateScienceSearchRequest`,
+ * `validateScienceGetRequest`, `parseScienceIdentifier`) that the
+ * interfaces' validate() methods delegate to.
+ *
+ * Scope rulings encoded here:
+ *   - `year` accepts ONLY the closed forms "2020" | "2018:2022"
+ *     (PRD AC-7/AC-7b). Empty, malformed, and reversed ranges throw.
+ *   - The shared validator judges ONLY `query` + `year`. `author`,
+ *     `venue`, and `type` pass through unjudged — per-control
+ *     accept/reject is the Adapter concern, and the `--type` union
+ *     vocabulary (including `component` rejection) lives at command
+ *     parse, never here.
+ *   - Identifier grammar is BARE forms only: DOI `^10\.\d{4,9}/`,
+ *     numeric PMID, arXiv `\d{4}\.\d{4,5}` plus the legacy
+ *     `archive/number` form (e.g. `cs/0501001`). A `doi:` prefix is not
+ *     one of the closed forms. Parsed once at the command layer.
+ */
+/**
+ * The five science supplier ids, in the design listing order. This is the
+ * PROVIDER_IDS insertion order, NOT the fan-out arm order (the
+ * openalex-first arm ordering is an executor concern).
+ */
+export declare const SCIENCE_SUPPLIER_IDS: readonly [
+    "arxiv",
+    "openalex",
+    "crossref",
+    "pubmed",
+    "europepmc"
+];
+/** A science supplier id. */
+export type ScienceSupplierId = (typeof SCIENCE_SUPPLIER_IDS)[number];
+/**
+ * Science search controls. Every field is optional. The shared validator
+ * judges only `year`; `author`/`venue`/`type` are Adapter-mapped and pass
+ * through unjudged at this layer.
+ */
+export interface ScienceControls {
+    /** Author filter; wire-consumed by openalex, crossref, pubmed. */
+    author?: string;
+    /** Closed forms only: "2020" | "2018:2022" (PRD AC-7/AC-7b). */
+    year?: string;
+    /** Venue filter; openalex and crossref native. */
+    venue?: string;
+    /** Content type; every supplier carries its own vocabulary. */
+    type?: string;
+}
+/**
+ * A science search request. `query` must contain at least one
+ * non-whitespace character; `validate` throws `ValidationError`
+ * otherwise.
+ */
+export interface ScienceSearchRequest {
+    query: string;
+    controls?: Readonly<ScienceControls>;
+}
+/**
+ * A science get request. `identifier` must be one of the bare closed
+ * forms (DOI, numeric PMID, arXiv id — see `parseScienceIdentifier`).
+ */
+export interface ScienceGetRequest {
+    identifier: string;
+}
+/**
+ * Normalized science work. Adapters populate this from their supplier
+ * response; commands merge, deduplicate, project, and present
+ * downstream. Supplier-only fields are discarded. Every field except
+ * `title` and `url` is optional — suppliers differ in coverage (e.g.
+ * Crossref lacks abstracts; arXiv serves preprints only).
+ */
+export interface ScienceWork {
+    title: string;
+    url: string;
+    /** Persistent identifiers as supplied by the responding source. */
+    identifiers?: {
+        doi?: string;
+        pmid?: string;
+        arxivId?: string;
+    };
+    authors?: string[];
+    year?: number;
+    venue?: string;
+    /** Abstract; absent when the supplier carries none. */
+    summary?: string;
+    citationCount?: number;
+    pdfUrl?: string;
+    openAccess?: boolean;
+    type?: string;
+    language?: string;
+    updated?: string;
+}
+/**
+ * Identity used to read and write a supplier-partitioned science cache
+ * entry. `credentialFingerprint` is the full lowercase SHA-256 hex digest
+ * of the active credential, or the empty string for keyless suppliers
+ * (keyless responses are user-independent, so the shared partition is
+ * correct). `request` is the normalized Capability request.
+ */
+export interface ScienceCacheIdentity {
+    readonly supplier: ScienceSupplierId;
+    readonly capability: "science.search" | "science.get" | "science.cite";
+    readonly credentialFingerprint: string;
+    readonly request: Readonly<ScienceSearchRequest | ScienceGetRequest>;
+}
+/**
+ * Science search Capability contract. Every supplier Adapter that
+ * supports search implements this interface and is consumed by the
+ * science executor.
+ */
+export interface ScienceSearchCapability {
+    /**
+     * Validate a request before any supplier access. Throws
+     * `ValidationError` for an empty or whitespace-only query and for a
+     * malformed `year` control; `UnsupportedOptionError` for controls the
+     * Adapter does not accept. Validation must occur before transport
+     * construction.
+     */
+    validate(request: ScienceSearchRequest): void;
+    /** Build the cache identity; called only after `validate` succeeds. */
+    cacheIdentity(request: ScienceSearchRequest): ScienceCacheIdentity;
+    /** Invoke the supplier and return normalized works; no retries here. */
+    invoke(request: ScienceSearchRequest, signal?: AbortSignal): Promise<readonly ScienceWork[]>;
+}
+/**
+ * Science get Capability contract. Identifier-addressed single-work
+ * fetch: the identifier is parsed once (DOI/PMID/arXiv-id) and routed to
+ * suppliers serving that id type.
+ */
+export interface ScienceGetCapability {
+    /**
+     * Validate a request before any supplier access. Throws
+     * `ValidationError` when the identifier is outside the grammar
+     * (`parseScienceIdentifier` returns null).
+     */
+    validate(request: ScienceGetRequest): void;
+    /** Build the cache identity; called only after `validate` succeeds. */
+    cacheIdentity(request: ScienceGetRequest): ScienceCacheIdentity;
+    /** Invoke the supplier and return one normalized work; no retries here. */
+    invoke(request: ScienceGetRequest, signal?: AbortSignal): Promise<ScienceWork>;
+}
+/**
+ * Science cite Capability contract. Typed but not shipped in v1 (PRD
+ * Non-goal: no science cite) — the type exists so provider descriptors
+ * can reference it later without contract churn. Ships when needed.
+ */
+export interface ScienceCiteCapability {
+    /** Identifier grammar plus citation direction. */
+    validate(request: ScienceGetRequest): void;
+    cacheIdentity(request: ScienceGetRequest): ScienceCacheIdentity;
+    invoke(request: ScienceGetRequest, signal?: AbortSignal): Promise<readonly ScienceWork[]>;
+}
+/**
+ * The science Capability surface an Adapter exposes. `cite` is named in
+ * the contract but ships later; it is absent here in v1.
+ */
+export interface ScienceCapability {
+    search: ScienceSearchCapability;
+    get: ScienceGetCapability;
+}
+/** The identifier kinds the closed grammar recognizes. */
+export type ScienceIdentifierKind = "doi" | "pmid" | "arxiv";
+/**
+ * Classify a bare science identifier. Returns `"doi"`, `"pmid"`, or
+ * `"arxiv"` when the identifier matches one of the closed forms, null
+ * otherwise. Bare forms only — prefixed input (e.g. `doi:10.1038/…`)
+ * returns null. Parsed once at the command layer; routing to suppliers
+ * serving that id type happens downstream.
+ */
+export declare function parseScienceIdentifier(identifier: string): ScienceIdentifierKind | null;
+/**
+ * Validate a science search request. Judges only the `query` (at least
+ * one non-whitespace character) and the `year` control grammar.
+ * `author`, `venue`, and `type` pass through unjudged — per-control
+ * accept/reject is the Adapter concern.
+ */
+export declare function validateScienceSearchRequest(request: ScienceSearchRequest): void;
+/**
+ * Validate a science get request. The identifier must be one of the bare
+ * closed forms (`parseScienceIdentifier` non-null); anything outside the
+ * grammar throws `ValidationError`.
+ */
+export declare function validateScienceGetRequest(request: ScienceGetRequest): void;
+//# sourceMappingURL=science.d.ts.map

package/dist/capabilities/science.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"science.d.ts","sourceRoot":"","sources":["../../src/capabilities/science.ts"],"names":[],"mappings":"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"}