ASTRA TypeScript SDK - Agentic Schema for Transparent Research Analysis

TypeScript SDK for validating and resolving ASTRA projects, published as @astra-spec/sdk.

For the schema, concepts, and authoring model, see the canonical ASTRA specification.

The SDK deliberately exposes two top-level project workflows:

• validateAnalysis() answers whether an authored ASTRA project is valid and returns structured issues.
• resolveAnalysis() validates the project and opens it as one recursive, serializable data structure for viewers and integrations.

See the versioned SDK documentation for focused integration guides and the complete API reference.

Install

npm install @astra-spec/sdk

Both workflows read through the small, host-neutral ProjectReader interface. For Node, create a reader rooted at the directory containing astra.yaml:

import { createNodeProjectReader } from "@astra-spec/sdk/node";

const reader = createNodeProjectReader("/path/to/project");

Validate a project

validateAnalysis() recursively checks the root astra.yaml, path-backed analyses, and universe files. It applies the bundled structural schema and the project-level semantic and reference checks in one operation. Every universe file is parsed and reference-checked; configuration-dependent conditions and constraints are evaluated from each root universe through the named child universes it selects.

import { validateAnalysis } from "@astra-spec/sdk";
import { createNodeProjectReader } from "@astra-spec/sdk/node";

const reader = createNodeProjectReader("/path/to/project");
const result = await validateAnalysis(reader);

if (!result.valid) {
  for (const issue of result.issues) {
    const location = [issue.file, issue.path].filter(Boolean).join(":");
    console.error(`${location}: ${issue.message}`);
  }
}

Each issue has a stable code, a human-readable message, the project-relative file, and, when available, the authored field path. Malformed YAML and other authored project problems return { valid: false, issues }. Reader failures and backend-enforced project-root escapes throw a ProjectLoadError because the project could not be read safely; a lexical escape written in Analysis.path is an authored validation issue.

Resolve a project

resolveAnalysis() runs the same complete validation internally, then resolves aliases, conditions, decision selections, provenance, evidence links, and artifact bindings for one universe. There is no need to call validateAnalysis() first unless the caller specifically wants a validation result instead of an exception.

import { resolveAnalysis } from "@astra-spec/sdk";
import { createNodeProjectReader } from "@astra-spec/sdk/node";

const reader = createNodeProjectReader("/path/to/project");
const bundle = await resolveAnalysis(reader, { universeId: "baseline" });

console.log(bundle.document.analysis.outputs);
console.log(bundle.bindings);

bundle.document is host-neutral JSON data containing the recursive resolved analysis tree. bundle.bindings maps materialized output canonical paths to project-relative artifact files and opaque cache tokens. A missing output artifact is not a project error: the output simply has no artifact descriptor or binding.

Output locations are derived without scanning results/. A root output lives at results/<universe>/<output>.<format>; an inline nested output lives at results/<universe>/<analysis>.<output>.<format> (with additional analysis IDs joined by dots). A path-backed analysis owns its own results/ directory and starts a fresh artifact namespace.

The resolver stats only these known paths. A binding is present when the file exists and carries an opaque cache token for downstream cache busting. The token is SHA-256 over the project-relative path, integer modification time in milliseconds, and byte size. It is a cheap equality token, not an artifact content hash; consumers must not parse or order it.

Invalid projects reject with AnalysisValidationError, whose issues use the same shape returned by validateAnalysis(). Loading and storage failures reject with ProjectLoadError; so does an explicitly requested root universe that does not exist.

Decode a transported bundle

TypeScript types do not validate data received through JSON, structured clone, storage, or an API. Use the SDK's runtime decoder at that boundary before passing a resolved bundle to a viewer or integration:

import {
  parseResolvedAnalysisBundle,
  ResolvedAnalysisBundleValidationError,
} from "@astra-spec/sdk";

const candidate: unknown = JSON.parse(serializedBundle);

try {
  const bundle = parseResolvedAnalysisBundle(candidate);
  render(bundle.document, bundle.bindings);
} catch (error) {
  if (error instanceof ResolvedAnalysisBundleValidationError) {
    console.error(error.issues);
  }
}

Alternatively, when diagnostics are not needed, use the boolean type guard:

import { isResolvedAnalysisBundle } from "@astra-spec/sdk";

if (isResolvedAnalysisBundle(candidate)) {
  render(candidate.document, candidate.bindings);
}

Despite its name, parseResolvedAnalysisBundle() does not call JSON.parse. It accepts an already-deserialized unknown, checks the complete known shape and current resolved schema version, and returns the original object unchanged. It performs no project I/O, reference checking, or semantic resolution. It rejects non-finite numeric fields and negative artifact byte sizes so accepted values remain safe to transport. Unknown additional fields are retained and ignored so producers can add metadata without breaking consumers of the current contract.

Derived lookups

The resolved document contains no lookup maps. Build them only when needed:

import { indexAnalysis } from "@astra-spec/sdk";

const index = indexAnalysis(bundle.document);
const output = index.recordByPath.get("stage.outputs.figure");
const owner = index.analysisByRecordPath.get("stage.outputs.figure"); // the "stage" node

Normalized cited DOI lists are also derived rather than duplicated:

import { collectCitedDois } from "@astra-spec/sdk";

const citedDois = collectCitedDois(bundle.document);

Other hosts

JupyterLab, editors, and browser-local integrations can implement the same read-only storage contract:

interface ProjectReader {
  readText(path: string): Promise<string>;
  stat(path: string): Promise<ProjectEntry | undefined>;
  readDirectory(path: string): Promise<ProjectDirectoryEntry[]>;
}

The contract is:

• Paths are normalized POSIX paths relative to the chosen project root; "" denotes the root. An adapter must prevent backend-specific escapes, such as symbolic links, by throwing ProjectPathError.
• readText() returns UTF-8 text for an existing file and rejects missing paths, directories, decoding errors, and backend failures.
• stat() returns undefined only for a missing path. A file entry contains a non-negative safe-integer byte size and Unix modification time in milliseconds; a directory entry needs only its type.
• readDirectory() returns immediate children with bare names and rejects a missing path, a non-directory, or a backend failure. Child order is not significant.

The SDK validates adapter responses. Invalid responses and ordinary backend failures become ProjectLoadError with READ_FAILED; ProjectPathError becomes PROJECT_PATH_ESCAPE. The package exports ProjectReader, ProjectEntry, and ProjectDirectoryEntry for adapter implementations.

ASTRA_SPEC_VERSION identifies the canonical schema bundled with this SDK.

Public API

This is the complete export inventory. Everything is imported from @astra-spec/sdk unless a different entry point is shown.

Project workflows and errors

Export	Kind	Purpose
validateAnalysis	function	Validate one complete project through a ProjectReader.
resolveAnalysis	function	Validate and resolve one project and selected universe.
ResolveAnalysisOptions	interface	Options for resolveAnalysis; currently contains universeId.
AnalysisValidationResult	interface	The { valid, issues } result returned by validation.
ValidationIssue	interface	One authored issue with a code, message, file, and optional field path.
AnalysisValidationError	class	Error thrown by resolution when authored validation fails.
ProjectLoadError	class	Error for reader, storage, root-boundary, and requested-universe failures.
ProjectLoadErrorCode	type	Union of the stable ProjectLoadError.code values.

Project access and path helpers

Export	Kind	Purpose
ProjectReader	interface	Host-neutral read-only access to one project root.
ProjectEntry	type	File or directory metadata returned by ProjectReader.stat.
ProjectDirectoryEntry	interface	One immediate child returned by ProjectReader.readDirectory.
ProjectPathError	class	Adapter signal that a backend path escapes the project root.
assertProjectPath	function	Assert that a path is normalized, POSIX, and project-relative.
joinProjectPath	function	Join project-relative paths while rejecting lexical root escapes.
projectDirname	function	Return the parent of a normalized project-relative path.

The Node adapter is a separate entry point:

Export	Entry point	Purpose
createNodeProjectReader	@astra-spec/sdk/node	Create a filesystem-backed reader rooted at an ASTRA project directory.

Version constants

Export	Kind	Purpose
ASTRA_SPEC_VERSION	constant	Version of the canonical ASTRA schema bundled with the SDK.
RESOLVED_ANALYSIS_SCHEMA_VERSION	constant	Version identifier for the resolved document contract.

Resolved data model

Export	Kind	Purpose
ResolvedAnalysisBundle	interface	Top-level result containing the document and artifact bindings.
ResolvedAnalysisDocument	interface	Serializable resolved analysis plus universe metadata.
UniverseSelection	interface	Effective universe, available universes, and selection source.
ResolvedRootAnalysis	type	Root analysis with guaranteed version and name.
ResolvedAnalysisNode	type	One recursive resolved analysis node.
ResolvedChildAnalysis	type	A resolved child node with a guaranteed id.
ResolvedRecord	type	Union of resolved inputs, outputs, decisions, and insights.
ResolvedRecordFields	interface	Fields common to resolved records, currently canonicalPath.
ResolvedInput	type	Input with its effective type and optional alias target.
ResolvedOutput	type	Output with activity, provenance, alias, and artifact metadata.
ResolvedDecision	type	Decision with normalized options, activity, and effective selection.
ResolvedOption	type	Normalized option with resolved supporting-insight paths.
ResolvedInsight	type	Finding or prior insight with resolved evidence.
ResolvedEvidence	type	Evidence with an optional resolved output path.
OutputProvenance	interface	Canonical input and decision dependencies of an output.
ArtifactDescriptor	interface	Materialized artifact metadata attached to a resolved output.
ArtifactBinding	interface	Output-to-file binding with its opaque cache token.

Resolved bundle decoding

Export	Kind	Purpose
isResolvedAnalysisBundle	function	Type guard for an already-deserialized resolved bundle.
parseResolvedAnalysisBundle	function	Return a valid transported bundle unchanged or throw structured diagnostics.
ResolvedAnalysisBundleValidationError	class	Error containing all structural issues found while decoding a bundle.
ResolvedAnalysisBundleValidationIssue	interface	One decoder issue with a stable code, JavaScript-style path, and message.
ResolvedAnalysisBundleValidationIssueCode	type	Union of decoder issue codes.

Derived helpers

Export	Kind	Purpose
AnalysisIndex	interface	Optional canonical-path lookup maps: analyses, records, and each record's declaring analysis.
indexAnalysis	function	Derive analysis, record, and record-owner lookup maps from a resolved document.
walkAnalyses	function	Iterate resolved analysis nodes depth-first in document order.
normalizeDoi	function	Normalize common DOI spellings without validating them.
collectCitedDois	function	Collect unique normalized DOIs in resolved document order.

Authored ASTRA types

These are deliberately permissive TypeScript shapes for ASTRA source data; they do not parse data or prove that it is valid. Use validateAnalysis or resolveAnalysis for the runtime contract.

Export	Kind	Purpose
Analysis	interface	Recursive authored analysis node.
Input	interface	Authored analysis input or input alias.
InputType	type	Allowed authored input kinds.
Output	interface	Authored output or output re-export.
OutputType	type	Allowed authored output kinds.
Decision	interface	Authored decision or inherited decision reference.
Option	interface	Authored decision option.
Universe	interface	Root universe document.
UniverseNode	interface	Recursive child selection inside a universe.
DecisionSelection	interface	Verbose decision-selection representation.
Insight	interface	Authored prior insight or finding.
Evidence	interface	Literature or artifact evidence for an insight.
TextQuoteSelector	interface	Exact quote and optional surrounding text.
FragmentSelector	interface	Fragment or page locator for evidence.
Recipe	interface	Authored command, resources, and container for an output.
Resources	interface	Authored compute resource requirements.

Links

• SDK documentation
• ASTRA specification
• @astra-spec/sdk on npm
• Releases

License

BSD-3-Clause. See LICENSE.