chore(release): 0.68.0

Author: pchalamet

CHANGELOG.md

@@ -3,8 +3,13 @@
 All notable changes to FScript are documented in this file.
 
 ## [Unreleased]
+
+## [0.68.0]
+
 - Added native `Task.spawn` and `Task.await` support with `'a task` types for concurrent thunk execution.
 
+**Full Changelog**: https://github.com/MagnusOpera/FScript/compare/0.67.1...0.68.0
+
 ## [0.67.1]
 
 

website/versioned_docs/version-0.68.0/embedding/overview.md

@@ -0,0 +1,30 @@
+---
+id: embedding-overview
+title: Embedding Overview
+slug: /embedding/overview
+---
+
+FScript is designed for host applications that embed a scripting language safely.
+
+## Embedding workflow
+
+1. Reference language/runtime packages.
+2. Build a host context.
+3. Register extern functions your scripts can call.
+4. Load scripts (with include resolution if needed).
+5. Resolve exported function signatures.
+6. Execute exported functions and handle results/errors.
+
+## NuGet packages
+
+- [`MagnusOpera.FScript.Language`](https://www.nuget.org/packages/MagnusOpera.FScript.Language)
+- [`MagnusOpera.FScript.Runtime`](https://www.nuget.org/packages/MagnusOpera.FScript.Runtime)
+- [`MagnusOpera.FScript.TypeProvider`](https://www.nuget.org/packages/MagnusOpera.FScript.TypeProvider)
+
+## Recommended reading order
+
+1. [Real-World Embedding (Load, Resolve Type, Execute)](./real-world-embedding)
+2. [F# Type Provider and Use Cases](./type-provider)
+3. [Register Extern Functions](./register-externs)
+4. [Resolver and Includes](./resolver-and-includes)
+5. [Sandbox and Safety](./sandbox-and-safety)

website/versioned_docs/version-0.68.0/embedding/real-world-embedding.md

@@ -0,0 +1,117 @@
+---
+id: real-world-embedding
+title: Real-World Embedding
+sidebar_label: Real-World Embedding
+slug: /embedding/real-world-embedding
+---
+
+This page shows a practical host flow with real concerns:
+
+1. load a script (with `import` support),
+2. inject host functions,
+3. resolve exported function types,
+4. execute exported functions safely.
+
+The example uses an in-memory source resolver so the host controls where imported source comes from.
+
+## Export host-callable bindings
+
+Use `[<export>]` on top-level bindings that the host must discover and invoke through embedding APIs such as `ScriptHost`.
+
+Bindings are part of the runtime host surface only when they are explicitly marked `[<export>]`. This makes the host-callable contract intentional: the host can list exported functions, resolve their signatures, read exported values, and invoke exported functions after loading the script.
+
+## End-to-end host example (F#)
+
+```fsharp
+open System
+open System.IO
+open FScript.Language
+open FScript.Runtime
+
+// 1) Entry script loaded from host memory.
+let root = "/virtual/workspace"
+let entryFile = Path.Combine(root, "main.fss")
+let normalizeVirtualPath (path: string) = Path.GetFullPath(path)
+let entrySource =
+    """
+import "shared/validation.fss" as Validation
+
+[<export>]
+let run (name: string) =
+  let normalized = Host.normalizeName name
+  Validation.validate normalized
+"""
+
+// 2) Imported files also come from host memory.
+let virtualSources =
+    Map [
+        normalizeVirtualPath (Path.Combine(root, "shared", "validation.fss")),
+        """
+let validate (name: string) =
+  if String.toUpper name = name then
+    $"VALID:{name}"
+  else
+    $"INVALID:{name}"
+"""
+    ]
+
+let resolveImportedSource (fullPath: string) : string option =
+    virtualSources |> Map.tryFind (Path.GetFullPath(fullPath))
+
+// 3) Inject host function(s) as externs.
+let normalizeNameExtern =
+    { Name = "Host.normalizeName"
+      Scheme = Forall([], TFun(TString, TString))
+      Arity = 1
+      Impl =
+        fun _ args ->
+            match args with
+            | [ VString s ] -> VString (s.Trim().ToUpperInvariant())
+            | _ -> failwith "Host.normalizeName expects one string argument" }
+
+let hostContext =
+    { HostContext.RootDirectory = root
+      DeniedPathGlobs = [] }
+
+let externs = normalizeNameExtern :: Registry.all hostContext
+
+// 4) Load script once (imports + extern typing + evaluation environment).
+let loaded =
+    ScriptHost.loadSourceWithIncludes
+        externs
+        root
+        entryFile
+        entrySource
+        resolveImportedSource
+
+// 5) Resolve exported function type/signature before execution.
+let runSignature = loaded.ExportedFunctionSignatures |> Map.find "run"
+let parameterTypes = runSignature.ParameterTypes |> List.map Types.typeToString
+let returnType = Types.typeToString runSignature.ReturnType
+
+printfn "run args: %A" parameterTypes
+printfn "run return: %s" returnType
+
+// 6) Execute exported function.
+let result = ScriptHost.invoke loaded "run" [ VString "  Ada  " ]
+
+match result with
+| VString value -> printfn "Result: %s" value
+| _ -> failwith "Unexpected result type"
+```
+
+In that example, `run` is marked `[<export>]` because the host needs to find it in the loaded script, inspect its signature, and invoke it through `ScriptHost`.
+
+## Why this pattern works well in production
+
+- **Load once, invoke many times**: keep parsed/inferred/evaluated script state in memory.
+- **Extern injection is explicit**: only functions you register are callable.
+- **Resolver is host-owned**: imports can come from DB, cache, or controlled virtual FS.
+- **Type resolution before invoke**: host can validate contracts before calling exports.
+
+## Common extensions
+
+- cache `LoadedScript` by tenant/project/version,
+- enforce root and deny-path policies via `HostContext`,
+- validate `ExportedFunctionSignatures` against host-side contracts,
+- wrap invocation in timeout/cancellation boundaries at host level.

website/versioned_docs/version-0.68.0/embedding/register-externs.md

@@ -0,0 +1,84 @@
+---
+id: register-externs
+title: Register Extern Functions
+slug: /embedding/register-externs
+---
+
+Externs are host functions exposed to scripts.
+
+Each extern defines:
+
+- name,
+- type scheme,
+- arity,
+- implementation.
+
+## Minimal pattern
+
+```fsharp
+{ Name = "My.add"
+  Scheme = Forall([], TFun(TInt, TFun(TInt, TInt)))
+  Arity = 2
+  Impl = fun ctx args -> ... }
+```
+
+## Why schemes matter
+
+Type schemes are injected into type inference, so script calls are type-checked before evaluation.
+
+## Real function injection example
+
+```fsharp
+open FScript.Language
+
+let slugifyExtern =
+    { Name = "Host.slugify"
+      Scheme = Forall([], TFun(TString, TString))
+      Arity = 1
+      Impl =
+        fun _ args ->
+            match args with
+            | [ VString s ] ->
+                s.Trim().ToLowerInvariant().Replace(" ", "-")
+                |> VString
+            | _ ->
+                failwith "Host.slugify expects one string argument" }
+```
+
+Use it with runtime externs:
+
+```fsharp
+open FScript.Runtime
+
+let hostContext =
+    { HostContext.RootDirectory = "."
+      DeniedPathGlobs = [] }
+
+let externs = slugifyExtern :: Registry.all hostContext
+```
+
+## Higher-order externs (callback into script)
+
+When an extern receives a script function as argument, use `ExternalCallContext.Apply` to invoke it.
+
+```fsharp
+let applyTwiceExtern =
+    { Name = "Host.applyTwice"
+      Scheme = Forall([], TFun(TFun(TInt, TInt), TFun(TInt, TInt)))
+      Arity = 2
+      Impl =
+        fun ctx args ->
+            match args with
+            | [ fn; VInt n ] ->
+                let once = ctx.Apply fn (VInt n)
+                ctx.Apply fn once
+            | _ ->
+                failwith "Host.applyTwice expects (int -> int) and int" }
+```
+
+## Design tips
+
+- Keep extern APIs small and explicit.
+- Prefer pure externs when possible.
+- Return option-like outcomes for recoverable failures.
+- Choose stable names; extern names are script-level API surface.

website/versioned_docs/version-0.68.0/embedding/resolver-and-includes.md

@@ -0,0 +1,55 @@
+---
+id: resolver-and-includes
+title: Resolver and Includes
+slug: /embedding/resolver-and-includes
+---
+
+When scripts use `import`, you can choose how included source is resolved.
+
+## Resolver-backed loading API
+
+Use `ScriptHost.loadSourceWithIncludes` when the entry script is not read directly from disk and imports must be resolved by the host:
+
+```fsharp
+ScriptHost.loadSourceWithIncludes
+    externs
+    rootDirectory
+    entryFile
+    entrySource
+    resolveImportedSource
+```
+
+`resolveImportedSource` has type:
+
+```fsharp
+string -> string option
+```
+
+It receives a normalized full path and should return source text (`Some`) or missing (`None`).
+
+## Resolver strategies
+
+- in-memory map (tests, cached scripts),
+- database-backed content,
+- object storage,
+- controlled virtual filesystem.
+
+## Minimal resolver example
+
+```fsharp
+open System.IO
+
+let sources =
+  Map [
+    Path.GetFullPath(Path.Combine("/virtual/shared", "common.fss")), "let inc x = x + 1"
+  ]
+
+let resolver path =
+  sources |> Map.tryFind (Path.GetFullPath(path))
+```
+
+## Guidance
+
+- Keep resolver deterministic: same path should produce same source for one run.
+- Normalize and constrain import roots to avoid path escape behavior.
+- Treat missing includes as normal host errors and surface clear diagnostics.

website/versioned_docs/version-0.68.0/embedding/sandbox-and-safety.md

@@ -0,0 +1,22 @@
+---
+id: sandbox-and-safety
+title: Sandbox and Safety
+slug: /embedding/sandbox-and-safety
+---
+
+FScript security is capability-based.
+
+Scripts can only perform actions that your host exposes.
+
+## Practical safety model
+
+- Do not expose risky externs by default.
+- Restrict filesystem scope with root/deny policies.
+- Use cancellation and timeouts for execution control.
+- Treat script execution as untrusted input handling.
+
+## Recommended defaults
+
+1. Expose read-only externs first.
+2. Add write/network capability only when required.
+3. Log extern calls for observability.