@extantape/onephylogeny-engine 0.0.0-stage → 0.1.0-alpha.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -0
- package/README.md +8 -2
- package/dist/index.d.ts +441 -0
- package/dist/index.js +1327 -0
- package/package.json +46 -3
- package/schemas/dataset.schema.json +77 -0
- package/schemas/examples.schema.json +165 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
Required Notice: Copyright 2026 EXTANT APE (https://github.com/ExtantApe)
|
|
2
|
+
|
|
3
|
+
# PolyForm Noncommercial License 1.0.0
|
|
4
|
+
|
|
5
|
+
<https://polyformproject.org/licenses/noncommercial/1.0.0>
|
|
6
|
+
|
|
7
|
+
## Acceptance
|
|
8
|
+
|
|
9
|
+
In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
|
|
10
|
+
|
|
11
|
+
## Copyright License
|
|
12
|
+
|
|
13
|
+
The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
|
|
14
|
+
|
|
15
|
+
## Distribution License
|
|
16
|
+
|
|
17
|
+
The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
|
|
18
|
+
|
|
19
|
+
## Notices
|
|
20
|
+
|
|
21
|
+
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
|
|
22
|
+
|
|
23
|
+
> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
|
|
24
|
+
|
|
25
|
+
## Changes and New Works License
|
|
26
|
+
|
|
27
|
+
The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
|
|
28
|
+
|
|
29
|
+
## Patent License
|
|
30
|
+
|
|
31
|
+
The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
|
|
32
|
+
|
|
33
|
+
## Noncommercial Purposes
|
|
34
|
+
|
|
35
|
+
Any noncommercial purpose is a permitted purpose.
|
|
36
|
+
|
|
37
|
+
## Personal Uses
|
|
38
|
+
|
|
39
|
+
Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
|
|
40
|
+
|
|
41
|
+
## Noncommercial Organizations
|
|
42
|
+
|
|
43
|
+
Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
|
|
44
|
+
|
|
45
|
+
## Fair Use
|
|
46
|
+
|
|
47
|
+
You may have "fair use" rights for the software under the law. These terms do not limit them.
|
|
48
|
+
|
|
49
|
+
## No Other Rights
|
|
50
|
+
|
|
51
|
+
These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
|
|
52
|
+
|
|
53
|
+
## Patent Defense
|
|
54
|
+
|
|
55
|
+
If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
|
|
56
|
+
|
|
57
|
+
## Violations
|
|
58
|
+
|
|
59
|
+
The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
|
|
60
|
+
|
|
61
|
+
## No Liability
|
|
62
|
+
|
|
63
|
+
***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
|
|
64
|
+
|
|
65
|
+
## Definitions
|
|
66
|
+
|
|
67
|
+
The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
|
|
68
|
+
|
|
69
|
+
**You** refers to the individual or entity agreeing to these terms.
|
|
70
|
+
|
|
71
|
+
**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
|
|
72
|
+
|
|
73
|
+
**Your licenses** are all the licenses granted to you for the software under these terms.
|
|
74
|
+
|
|
75
|
+
**Use** means anything you do with the software requiring one of your licenses.
|
package/README.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @extantape/onephylogeny-engine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
OnePhylogeny engine: runs profiles end to end with immutable run records and structured logs: fetch, anchor, gate, build panels, validate, test samples and build trees through replaceable ports.
|
|
4
|
+
|
|
5
|
+
See the [repository](https://github.com/ExtantApe/OnePhylogeny) for documentation.
|
|
6
|
+
|
|
7
|
+
## JSON Schemas
|
|
8
|
+
|
|
9
|
+
`schemas/examples.schema.json` and `schemas/dataset.schema.json` describe a built panel's `examples.json` and `dataset.json` (see `onephylogeny verify`).
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,441 @@
|
|
|
1
|
+
import { ValidationInput, FullValidation, RunEvent, Id, FindingStatus, PanelBundle, Diagnostic, PanelStatus, MarkerPlace, ExternalId, RecordDecision, Curation, HypothesisVerdict, StatedTest, ArtifactPointer, Profile, HypothesisClaim, Run, SequenceRecord, Result, RunComparison, LinkedRecord, PanelComparison } from '@extantape/onephylogeny-core';
|
|
2
|
+
import { NcbiOptions, FoundPaper } from '@extantape/onephylogeny-acquire';
|
|
3
|
+
|
|
4
|
+
/** Where files live. A folder on disk, in the CLI and the Mac app. */
|
|
5
|
+
interface Store {
|
|
6
|
+
read(path: string): Promise<string>;
|
|
7
|
+
/** Must be atomic: a crash leaves the old file or the new one, never half of it. */
|
|
8
|
+
write(path: string, text: string): Promise<void>;
|
|
9
|
+
exists(path: string): Promise<boolean>;
|
|
10
|
+
/** Adds to a log without rewriting it. Optional: without it, logs are written whole. */
|
|
11
|
+
append?(path: string, text: string): Promise<void>;
|
|
12
|
+
/** Names of the folders inside a folder, sorted; none if it doesn't exist. Optional: only hypothesis tests list folders, and without it a claim must name its panel version. */
|
|
13
|
+
folders?(path: string): Promise<string[]>;
|
|
14
|
+
}
|
|
15
|
+
/** How native programs run. Only tree building needs one. */
|
|
16
|
+
interface ToolRunner {
|
|
17
|
+
version(tool: string): Promise<string | null>;
|
|
18
|
+
run(tool: string, args: string[], options: {
|
|
19
|
+
cwd: string;
|
|
20
|
+
}): Promise<{
|
|
21
|
+
code: number;
|
|
22
|
+
stdout: string;
|
|
23
|
+
stderr: string;
|
|
24
|
+
}>;
|
|
25
|
+
}
|
|
26
|
+
type ValidationReports = FullValidation;
|
|
27
|
+
/** Heavy pure calculations, which an app can run off its interface thread. */
|
|
28
|
+
type Compute = {
|
|
29
|
+
validate?: (input: ValidationInput, signal?: AbortSignal) => Promise<ValidationReports>;
|
|
30
|
+
};
|
|
31
|
+
type EngineContext = {
|
|
32
|
+
store: Store;
|
|
33
|
+
ncbi: Omit<NcbiOptions, 'log'>;
|
|
34
|
+
tools?: ToolRunner;
|
|
35
|
+
now?: () => Date;
|
|
36
|
+
onEvent?: (event: RunEvent) => void;
|
|
37
|
+
/** Cancels a run at its next safe point. */
|
|
38
|
+
signal?: AbortSignal;
|
|
39
|
+
compute?: Compute;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
type ArtifactType = 'accession-list' | 'raw-records' | 'anchored-records' | 'gated-records' | 'panel' | 'validation' | 'sample-result' | 'tree';
|
|
43
|
+
type ToolIdentity = {
|
|
44
|
+
name: string;
|
|
45
|
+
version: string;
|
|
46
|
+
};
|
|
47
|
+
type ArtifactRef = {
|
|
48
|
+
type: ArtifactType;
|
|
49
|
+
key: string;
|
|
50
|
+
};
|
|
51
|
+
/** Written last. Its presence is what says a step finished, so a crash can't leave something that looks complete. */
|
|
52
|
+
type ArtifactManifest = {
|
|
53
|
+
schemaVersion: 1;
|
|
54
|
+
type: ArtifactType;
|
|
55
|
+
key: string;
|
|
56
|
+
step: {
|
|
57
|
+
name: string;
|
|
58
|
+
version: number;
|
|
59
|
+
};
|
|
60
|
+
inputs: ArtifactRef[];
|
|
61
|
+
parameters: unknown;
|
|
62
|
+
tools: ToolIdentity[];
|
|
63
|
+
files: {
|
|
64
|
+
name: string;
|
|
65
|
+
sha256: string;
|
|
66
|
+
}[];
|
|
67
|
+
createdAt: string;
|
|
68
|
+
};
|
|
69
|
+
type Artifact = {
|
|
70
|
+
manifest: ArtifactManifest;
|
|
71
|
+
read: (name: string) => Promise<string>;
|
|
72
|
+
};
|
|
73
|
+
/** Loads an artifact for use, refusing the wrong type or anything that has changed since it was made. */
|
|
74
|
+
declare function loadArtifact(store: Store, ref: ArtifactRef): Promise<Artifact>;
|
|
75
|
+
type TraceNode = {
|
|
76
|
+
type: ArtifactType;
|
|
77
|
+
key: string;
|
|
78
|
+
step: string;
|
|
79
|
+
parameters: unknown;
|
|
80
|
+
tools: ToolIdentity[];
|
|
81
|
+
createdAt: string;
|
|
82
|
+
inputs: TraceNode[];
|
|
83
|
+
};
|
|
84
|
+
/** Follows an artifact back through everything that produced it. */
|
|
85
|
+
declare function traceArtifact(store: Store, ref: ArtifactRef): Promise<TraceNode>;
|
|
86
|
+
|
|
87
|
+
/** Every failure has a stable code, plain words, and what to do next. */
|
|
88
|
+
type ErrorCode = 'invalid-profile' | 'empty-search' | 'empty-panel' | 'source-failed' | 'reference-missing' | 'raw-file-changed' | 'artifact-missing' | 'artifact-wrong-type' | 'artifact-corrupt' | 'step-output-invalid' | 'panel-version-exists' | 'panel-outdated' | 'panel-missing' | 'panel-changed' | 'tool-missing' | 'tool-failed' | 'run-missing' | 'cancelled' | 'panel-unsealed' | 'examples-differ' | 'reference-unannotated';
|
|
89
|
+
declare class EngineError extends Error {
|
|
90
|
+
readonly code: ErrorCode;
|
|
91
|
+
readonly action?: string | undefined;
|
|
92
|
+
constructor(code: ErrorCode, message: string, action?: string | undefined);
|
|
93
|
+
}
|
|
94
|
+
declare const isCancelled: (e: unknown) => boolean;
|
|
95
|
+
|
|
96
|
+
/** Bump with each engine release. Recorded in every run, panel and result. */
|
|
97
|
+
declare const ENGINE_VERSION = "0.1.0-alpha.8";
|
|
98
|
+
declare const profilePaths: (profileId: string) => {
|
|
99
|
+
profile: string;
|
|
100
|
+
curation: string;
|
|
101
|
+
latest: string;
|
|
102
|
+
run: (id: string) => string;
|
|
103
|
+
panel: (id: string, version: string) => string;
|
|
104
|
+
results: string;
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* A panel as a dataset (roadmap stage 2; docs/architecture/adr/0006-panel-dataset.md). Beside the sealed `panel.json`
|
|
109
|
+
* and `panel.fasta`, a built panel's folder carries example sequences with the results they gave when it was built,
|
|
110
|
+
* and a manifest of every file's hash. `verifyDataset` checks the hashes and the seal, then reruns the examples, so a
|
|
111
|
+
* panel copied to another machine, or read by another version of the software, is shown to give the same answers.
|
|
112
|
+
*/
|
|
113
|
+
/** What an example must give again. Statuses per group and how each pair resolved, or the codes that refused it. */
|
|
114
|
+
type ExampleExpectation = {
|
|
115
|
+
outcome: 'result';
|
|
116
|
+
statuses: Record<Id, FindingStatus>;
|
|
117
|
+
pairs: Record<string, string>;
|
|
118
|
+
} | {
|
|
119
|
+
outcome: 'refused';
|
|
120
|
+
codes: string[];
|
|
121
|
+
};
|
|
122
|
+
type PanelExample = {
|
|
123
|
+
id: string;
|
|
124
|
+
kind: 'member' | 'fragment' | 'control';
|
|
125
|
+
/** Why this example is here, in words. */
|
|
126
|
+
note: string;
|
|
127
|
+
sequence: string;
|
|
128
|
+
expected: ExampleExpectation;
|
|
129
|
+
};
|
|
130
|
+
type PanelExamples = {
|
|
131
|
+
schemaVersion: 1;
|
|
132
|
+
panel: {
|
|
133
|
+
id: Id;
|
|
134
|
+
version: string;
|
|
135
|
+
checksum: string;
|
|
136
|
+
};
|
|
137
|
+
producedBy: {
|
|
138
|
+
name: string;
|
|
139
|
+
version: string;
|
|
140
|
+
}[];
|
|
141
|
+
examples: PanelExample[];
|
|
142
|
+
};
|
|
143
|
+
/** The files a dataset's manifest covers, when present. `artifact.json` is left out: it points into one machine's store. */
|
|
144
|
+
declare const DATASET_FILES: readonly ["panel.json", "panel.fasta", "validation.json", "diagnostics.json", "examples.json", "README.md"];
|
|
145
|
+
type DatasetManifest = {
|
|
146
|
+
schemaVersion: 1;
|
|
147
|
+
panel: {
|
|
148
|
+
id: Id;
|
|
149
|
+
version: string;
|
|
150
|
+
checksum: string;
|
|
151
|
+
};
|
|
152
|
+
files: Record<string, string>;
|
|
153
|
+
/** The software that wrote the examples. A copy is compatible with any version whose rerun of the examples matches. */
|
|
154
|
+
builtWith?: {
|
|
155
|
+
name: string;
|
|
156
|
+
version: string;
|
|
157
|
+
}[];
|
|
158
|
+
/** The panel's sources, as it cites them. */
|
|
159
|
+
citations?: string[];
|
|
160
|
+
};
|
|
161
|
+
/**
|
|
162
|
+
* A README for the folder, so the dataset reads without the tool: what the panel is for, its groups and regions, what it
|
|
163
|
+
* can't speak to, how far it has been validated, how to check a copy, and what to cite. Built from the sealed panel
|
|
164
|
+
* alone, so it never holds a coordinate or a site.
|
|
165
|
+
*/
|
|
166
|
+
declare function datasetReadme(bundle: PanelBundle, examples: PanelExamples): string;
|
|
167
|
+
type SampleTester = (sequence: string, queryId: string, bundle: PanelBundle) => {
|
|
168
|
+
result: {
|
|
169
|
+
findings: {
|
|
170
|
+
group: Id;
|
|
171
|
+
status: FindingStatus;
|
|
172
|
+
}[];
|
|
173
|
+
pairs: {
|
|
174
|
+
a: Id;
|
|
175
|
+
b: Id;
|
|
176
|
+
state: string;
|
|
177
|
+
favors?: Id;
|
|
178
|
+
}[];
|
|
179
|
+
} | null;
|
|
180
|
+
diagnostics: Diagnostic[];
|
|
181
|
+
};
|
|
182
|
+
declare function expectationOf(outcome: ReturnType<SampleTester>): ExampleExpectation;
|
|
183
|
+
/**
|
|
184
|
+
* Chooses examples from the panel itself, the same way every time: per group, the member with location evidence
|
|
185
|
+
* covering the most columns (ties by record ID); a 300-base fragment from the middle of the first of those; and a
|
|
186
|
+
* control that isn't the marker at all, which the panel must refuse.
|
|
187
|
+
*/
|
|
188
|
+
declare function chooseExamples(bundle: PanelBundle): Omit<PanelExample, 'expected'>[];
|
|
189
|
+
declare function makeExamples(bundle: PanelBundle, test: SampleTester): PanelExamples;
|
|
190
|
+
/** Reruns every example. Each one that no longer gives what it gave at build time is an error. */
|
|
191
|
+
declare function checkExamples(examples: PanelExamples, bundle: PanelBundle, test: SampleTester): Diagnostic[];
|
|
192
|
+
/** Writes `examples.json` and then `dataset.json` into a built panel's folder. Refuses to replace different examples. */
|
|
193
|
+
declare function writeDataset(store: Store, dir: string, bundle: PanelBundle, test: SampleTester): Promise<DatasetManifest>;
|
|
194
|
+
/**
|
|
195
|
+
* Everything a copy of a panel needs to be trusted: the manifest's hashes, the panel's seal, and the examples rerun.
|
|
196
|
+
* Reads only. `load` is the engine's `loadPanel`, which checks the seal.
|
|
197
|
+
*/
|
|
198
|
+
declare function verifyDataset(store: Store, dir: string, load: (store: Store, dir: string) => Promise<PanelBundle>, test: SampleTester): Promise<{
|
|
199
|
+
diagnostics: Diagnostic[];
|
|
200
|
+
checked: {
|
|
201
|
+
files: number;
|
|
202
|
+
examples: number;
|
|
203
|
+
};
|
|
204
|
+
}>;
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Sample routing (roadmap stage 2, item 5): given a sequence, which installed panels apply? Each panel's own reference
|
|
208
|
+
* and record checks decide, the same ones `testSample` runs first, so a panel that's suggested will accept the sequence.
|
|
209
|
+
* Routing only suggests; it never picks a result, and a person chooses which panel to test against. Every panel that
|
|
210
|
+
* applies is listed (ADR 0009, decision 6): a whole mitogenome gets its mitogenome panel and, when one is installed, a
|
|
211
|
+
* cytb panel too, with cytb located inside it. Nothing is ranked by probability.
|
|
212
|
+
*/
|
|
213
|
+
type RouteSuggestion = {
|
|
214
|
+
panel: {
|
|
215
|
+
id: Id;
|
|
216
|
+
version: string;
|
|
217
|
+
status: PanelStatus;
|
|
218
|
+
};
|
|
219
|
+
applies: boolean;
|
|
220
|
+
/** Why it applies or doesn't, in plain words. */
|
|
221
|
+
reason: string;
|
|
222
|
+
identity?: number;
|
|
223
|
+
alignedColumns?: number;
|
|
224
|
+
/** Windows the sequence covers with at least the panel's minimum shared columns. */
|
|
225
|
+
windows: Id[];
|
|
226
|
+
/** True, false, or unknown when the sequence carries no taxon claim. */
|
|
227
|
+
taxonMatches: boolean | 'unknown';
|
|
228
|
+
/** The panel's marker: a gene's name, or "mitogenome". */
|
|
229
|
+
marker: string;
|
|
230
|
+
/** Where the panel's marker was found in a longer sequence, such as cytb in a whole mitogenome. 0-based, half-open. */
|
|
231
|
+
located?: {
|
|
232
|
+
start: number;
|
|
233
|
+
end: number;
|
|
234
|
+
strand: '+' | '-';
|
|
235
|
+
};
|
|
236
|
+
/** Panels whose windows are genes: reference columns in the covered windows, each counted once where genes overlap. */
|
|
237
|
+
windowColumns?: number;
|
|
238
|
+
};
|
|
239
|
+
/** The part of a sample a panel tests: the whole sequence, or the panel's marker cut out of a much longer one. */
|
|
240
|
+
type SampleMarker = {
|
|
241
|
+
sequence: string;
|
|
242
|
+
located?: MarkerPlace;
|
|
243
|
+
manyPlaces?: MarkerPlace[];
|
|
244
|
+
};
|
|
245
|
+
/**
|
|
246
|
+
* A sample many times longer than a gene panel's reference, such as a whole mitogenome tested against a cytb panel,
|
|
247
|
+
* has the marker cut out by similarity first, as fetch does for records (ADR 0009, decision 6). The cut-out part then
|
|
248
|
+
* goes through the panel's usual checks. Two plausible places is a refusal, never a guess. A sample isn't known to be
|
|
249
|
+
* circular (only a GenBank record says so), so a marker across its origin isn't joined up.
|
|
250
|
+
*/
|
|
251
|
+
declare function markerInSample(sequence: string, bundle: PanelBundle): SampleMarker;
|
|
252
|
+
/** Where a located marker is, in plain words. Positions are 1-based, as a person counts, and include a few flanking bases the aligner trims. */
|
|
253
|
+
declare const placeText: (marker: string, p: MarkerPlace) => string;
|
|
254
|
+
declare function routeSample(sequence: string, bundles: PanelBundle[], options?: {
|
|
255
|
+
taxonClaim?: ExternalId;
|
|
256
|
+
}): RouteSuggestion[];
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* Decision history (roadmap stage 3): every saved change to a curation, field by field, with when, by whom and why.
|
|
260
|
+
* An append-only JSON Lines file beside `curation.json`, readable without the tool. Saving through `saveCuration` is the
|
|
261
|
+
* only way the app and the CLI change a curation, so the history can't be skipped.
|
|
262
|
+
*/
|
|
263
|
+
type CurationChange = {
|
|
264
|
+
record: Id;
|
|
265
|
+
field: keyof RecordDecision;
|
|
266
|
+
from?: unknown;
|
|
267
|
+
to?: unknown;
|
|
268
|
+
};
|
|
269
|
+
type CurationHistoryEntry = {
|
|
270
|
+
at: string;
|
|
271
|
+
by?: string;
|
|
272
|
+
reason?: string;
|
|
273
|
+
changes: CurationChange[];
|
|
274
|
+
};
|
|
275
|
+
declare const historyPath: (profileId: string) => string;
|
|
276
|
+
/** Field-by-field differences between two curations, in record then field order. */
|
|
277
|
+
declare function curationDiff(before: Curation, after: Curation): CurationChange[];
|
|
278
|
+
/** Saves a curation and appends what changed to its history. Saving without a change writes nothing. */
|
|
279
|
+
declare function saveCuration(store: Store, profileId: string, next: Curation, meta?: {
|
|
280
|
+
at?: string;
|
|
281
|
+
by?: string;
|
|
282
|
+
reason?: string;
|
|
283
|
+
}): Promise<CurationHistoryEntry | null>;
|
|
284
|
+
/** The history, oldest first, optionally for one record. A damaged line is reported, not skipped silently. */
|
|
285
|
+
declare function readCurationHistory(store: Store, profileId: string, record?: Id): Promise<{
|
|
286
|
+
entries: CurationHistoryEntry[];
|
|
287
|
+
damagedLines: number[];
|
|
288
|
+
}>;
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Hypothesis chat, engine side (roadmap stage 9, ADR 0013). Finds the saved artifacts a claim needs in the store, loads
|
|
292
|
+
* them with the store's own file checks, and hands them to core's `planTest` and `runTest`. `filesVerified` is always
|
|
293
|
+
* worked out here from the recorded hashes, never taken from a caller. Everything here only reads: no run record, log,
|
|
294
|
+
* cache or result is written, and nothing is fetched or built.
|
|
295
|
+
*/
|
|
296
|
+
/** Where an artifact named in the stated test was found, so running reads exactly that again. */
|
|
297
|
+
type HypothesisSource =
|
|
298
|
+
/** A built panel's folder. `artifact` is the panel artifact its `artifact.json` names, when there is one. */
|
|
299
|
+
{
|
|
300
|
+
kind: 'panel';
|
|
301
|
+
pointer: ArtifactPointer;
|
|
302
|
+
folder: string;
|
|
303
|
+
artifact?: ArtifactRef;
|
|
304
|
+
}
|
|
305
|
+
/** A saved sample result, as `runSample` copies it into `results/`, and the artifact its run recorded. */
|
|
306
|
+
| {
|
|
307
|
+
kind: 'result';
|
|
308
|
+
pointer: ArtifactPointer;
|
|
309
|
+
file: string;
|
|
310
|
+
artifact?: ArtifactRef;
|
|
311
|
+
};
|
|
312
|
+
/** A stated test, with where each artifact it names was found and what the loading noticed on the way. */
|
|
313
|
+
type HypothesisPlan = {
|
|
314
|
+
stated: StatedTest;
|
|
315
|
+
/** The profile whose folders were read, or absent for a lone panel folder. */
|
|
316
|
+
profile?: string;
|
|
317
|
+
sources: HypothesisSource[];
|
|
318
|
+
/** Plain words: panels or results that were skipped or couldn't be checked, and why. */
|
|
319
|
+
notes: string[];
|
|
320
|
+
};
|
|
321
|
+
type HypothesisOutcome = HypothesisVerdict & {
|
|
322
|
+
notes: string[];
|
|
323
|
+
};
|
|
324
|
+
/**
|
|
325
|
+
* States the test for a claim against a profile's saved panels and results, before anything runs. Finds every panel
|
|
326
|
+
* version and every saved result for the claim's sample, loads each with its file and seal checks, and asks core's
|
|
327
|
+
* `planTest` which of them the test will read. Writes nothing.
|
|
328
|
+
*/
|
|
329
|
+
declare function testHypothesis(ctx: EngineContext, profile: Profile, claim: HypothesisClaim): Promise<HypothesisPlan>;
|
|
330
|
+
/**
|
|
331
|
+
* The same for a single panel folder outside any workspace, such as a downloaded dataset (`--dir`). Its files are
|
|
332
|
+
* checked against its `dataset.json`. A folder holds no saved results, so only `groups-distinct` can be tested here.
|
|
333
|
+
*/
|
|
334
|
+
declare function testHypothesisOnPanel(ctx: EngineContext, folder: string, claim: HypothesisClaim): Promise<HypothesisPlan>;
|
|
335
|
+
/**
|
|
336
|
+
* Runs a stated test. Re-loads exactly the artifacts it names, from where they were found, with the same file and seal
|
|
337
|
+
* checks, then runs core's `runTest`, which refuses anything that changed since the test was stated. A plan that wasn't
|
|
338
|
+
* testable comes back `untestable with this data` without reading anything. Writes nothing.
|
|
339
|
+
*/
|
|
340
|
+
declare function runHypothesis(ctx: EngineContext, plan: HypothesisPlan): Promise<HypothesisOutcome>;
|
|
341
|
+
|
|
342
|
+
type RecordOutcome = {
|
|
343
|
+
record: string;
|
|
344
|
+
organism?: string;
|
|
345
|
+
status: 'passed' | 'excluded';
|
|
346
|
+
diagnostics: Diagnostic[];
|
|
347
|
+
columns: number;
|
|
348
|
+
identity: number;
|
|
349
|
+
extractedFrom: 'annotation' | 'located' | 'whole-record';
|
|
350
|
+
};
|
|
351
|
+
type FetchOutcome = {
|
|
352
|
+
run: Run;
|
|
353
|
+
records: SequenceRecord[];
|
|
354
|
+
outcomes: RecordOutcome[];
|
|
355
|
+
};
|
|
356
|
+
/**
|
|
357
|
+
* Fetches everything a profile selects, keeps raw files, anchors and checks each record, and writes the sheet and log.
|
|
358
|
+
* Each stage reuses earlier work when its inputs and settings are unchanged.
|
|
359
|
+
*/
|
|
360
|
+
declare function fetchAndAnchor(ctx: EngineContext, profile: Profile, options?: {
|
|
361
|
+
batchSize?: number;
|
|
362
|
+
allowEmpty?: boolean;
|
|
363
|
+
}): Promise<FetchOutcome>;
|
|
364
|
+
/** Studies built from GenBank records of a profile's species and marker, placed on the reference. */
|
|
365
|
+
declare function findRecordStudies(ctx: EngineContext, profile: Profile, onProgress?: (done: number, total: number) => void): Promise<{
|
|
366
|
+
papers: FoundPaper[];
|
|
367
|
+
columns: number;
|
|
368
|
+
query: string;
|
|
369
|
+
}>;
|
|
370
|
+
/** Looks up what PubMed links to one paper, then sorts those records by species and gene and places them. */
|
|
371
|
+
declare function findPaperRecords(ctx: EngineContext, profile: Profile, pmid: string): Promise<{
|
|
372
|
+
linked: LinkedRecord[];
|
|
373
|
+
columns: number;
|
|
374
|
+
}>;
|
|
375
|
+
type PanelBuildOutcome = {
|
|
376
|
+
bundle: PanelBundle;
|
|
377
|
+
diagnostics: Diagnostic[];
|
|
378
|
+
validation: ValidationReports;
|
|
379
|
+
unassigned: number;
|
|
380
|
+
run: Run;
|
|
381
|
+
published: boolean;
|
|
382
|
+
};
|
|
383
|
+
/** The records of a finished fetch run (the latest when no ID is given), as the panel build reads them. */
|
|
384
|
+
declare function loadRunRecords(store: Store, profileId: string, runId?: string): Promise<SequenceRecord[]>;
|
|
385
|
+
/** Builds and validates a candidate panel from a finished fetch run and the curation file. */
|
|
386
|
+
declare function buildPanelFromRun(ctx: EngineContext, profile: Profile, curation: Curation, id?: string): Promise<PanelBuildOutcome>;
|
|
387
|
+
declare function loadPanel(store: Store, dir: string): Promise<PanelBundle>;
|
|
388
|
+
/** The versions built for a profile's panel, oldest first. Every one is listed, so no attempt can be left out. */
|
|
389
|
+
declare function panelVersions(profile: Profile, folders: string[]): string[];
|
|
390
|
+
/** Compares two built versions. Both must still match their seals. */
|
|
391
|
+
declare function comparePanelVersions(store: Store, profile: Profile, a: string, b: string): Promise<RunComparison>;
|
|
392
|
+
/** The same comparison, with each version's validation outcomes by window paired beside it and labels to show it with. */
|
|
393
|
+
declare function panelVersionComparison(store: Store, profile: Profile, a: string, b: string): Promise<PanelComparison>;
|
|
394
|
+
type SampleOutcome = {
|
|
395
|
+
result: Result;
|
|
396
|
+
diagnostics: Diagnostic[];
|
|
397
|
+
aligned: string;
|
|
398
|
+
insertions: number;
|
|
399
|
+
deletions: number;
|
|
400
|
+
identity: number;
|
|
401
|
+
clipped: {
|
|
402
|
+
start: number;
|
|
403
|
+
end: number;
|
|
404
|
+
};
|
|
405
|
+
} | {
|
|
406
|
+
result: null;
|
|
407
|
+
diagnostics: Diagnostic[];
|
|
408
|
+
};
|
|
409
|
+
/** Tests one sequence against one panel. Pure TypeScript: runs in the app, the CLI or a hosted site. */
|
|
410
|
+
declare function testSample(sequence: string, queryId: string, bundle: PanelBundle, options?: {
|
|
411
|
+
runId?: string;
|
|
412
|
+
}): SampleOutcome;
|
|
413
|
+
/** Tests a sequence with a full record: a saved result that traces back to its panel, the records and raw files. */
|
|
414
|
+
declare function runSample(ctx: EngineContext, profile: Profile, sequence: string, queryId: string): Promise<SampleOutcome & {
|
|
415
|
+
run: Run;
|
|
416
|
+
artifact: ArtifactRef;
|
|
417
|
+
}>;
|
|
418
|
+
type TreeOutcome = {
|
|
419
|
+
tool: string;
|
|
420
|
+
version: string;
|
|
421
|
+
newick: string;
|
|
422
|
+
tips: {
|
|
423
|
+
id: string;
|
|
424
|
+
members: string[];
|
|
425
|
+
}[];
|
|
426
|
+
run: Run;
|
|
427
|
+
artifact: ArtifactRef;
|
|
428
|
+
};
|
|
429
|
+
/** Builds a tree with IQ-TREE from one coverage window of a run's records. */
|
|
430
|
+
declare function buildTree(ctx: EngineContext, profile: Profile, options: {
|
|
431
|
+
runId?: string;
|
|
432
|
+
absoluteDir: string;
|
|
433
|
+
tool?: string;
|
|
434
|
+
window?: {
|
|
435
|
+
start: number;
|
|
436
|
+
end: number;
|
|
437
|
+
};
|
|
438
|
+
minCoverage?: number;
|
|
439
|
+
}): Promise<TreeOutcome>;
|
|
440
|
+
|
|
441
|
+
export { type ArtifactManifest, type ArtifactRef, type ArtifactType, type Compute, type CurationChange, type CurationHistoryEntry, DATASET_FILES, type DatasetManifest, ENGINE_VERSION, type EngineContext, EngineError, type ErrorCode, type ExampleExpectation, type FetchOutcome, type HypothesisOutcome, type HypothesisPlan, type HypothesisSource, type PanelBuildOutcome, type PanelExample, type PanelExamples, type RecordOutcome, type RouteSuggestion, type SampleMarker, type SampleOutcome, type SampleTester, type Store, type ToolRunner, type TraceNode, type TreeOutcome, type ValidationReports, buildPanelFromRun, buildTree, checkExamples, chooseExamples, comparePanelVersions, curationDiff, datasetReadme, expectationOf, fetchAndAnchor, findPaperRecords, findRecordStudies, historyPath, isCancelled, loadArtifact, loadPanel, loadRunRecords, makeExamples, markerInSample, panelVersionComparison, panelVersions, placeText, profilePaths, readCurationHistory, routeSample, runHypothesis, runSample, saveCuration, testHypothesis, testHypothesisOnPanel, testSample, traceArtifact, verifyDataset, writeDataset };
|