From 191bca981cf5b2932fb5d345202cf380ec7a25f3 Mon Sep 17 00:00:00 2001
From: zrr1999 <2742392377@qq.com>
Date: Mon, 13 Apr 2026 00:28:13 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat(platform):=20add=20startup=20c?=
 =?UTF-8?q?ontract=20module?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md                | 17 ++++++++++++++++-
 spore.toml               |  6 ++++++
 src/host.sp              |  5 +++--
 src/platform_contract.sp | 13 +++++++++++++
 4 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 src/platform_contract.sp

diff --git a/README.md b/README.md
index 8a19506..6a2c0fc 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,8 @@ This repository currently keeps `examples/` limited to files that PR CI validate
 basic-cli/
 ├── spore.toml         # Platform manifest
 ├── src/
-│   ├── host.sp        # Default platform entry point
+│   ├── host.sp        # Compatibility runtime entry point
+│   ├── platform_contract.sp
 │   └── basic_cli/     # Spore API modules, checked and built in CI
 │       ├── stdout.sp  # Standard output operations
 │       ├── stdin.sp   # Standard input operations
@@ -65,10 +66,24 @@ basic-cli/
 └── examples/          # Canonical examples that format/check/build in CI
 ```
 
+## Contract Surface (MVP)
+
+The current Platform contract MVP is intentionally split across two artifacts:
+
+1. `spore.toml` `[platform]` metadata names the contract module, the startup contract symbol, the adapter function, and the handled capabilities.
+2. `src/platform_contract.sp` owns the startup contract itself:
+   - a hole-backed `main` function carries the authoritative startup signature
+   - `main_for_host` is the Platform-owned adapter that receives the application startup function
+
+Applications targeting `basic-cli` must implement the same startup function name/signature in their entry module. When the compiler starts reading Platform contracts from packages, `spec` items attached to the Platform contract and the application implementation will both have to hold.
+
+`src/host.sp` remains as a compatibility copy of the adapter while the compiler still hardcodes platform startup behavior.
+
 ## Tutorial Contract
 
 - `examples/` is for truthful, CI-validated examples only.
 - `src/basic_cli/` is the API surface for the platform modules themselves.
+- `src/platform_contract.sp` is the package-owned startup contract surface.
 - Only add `tests/` when the repo has real Spore-side regression coverage worth running with `spore test`.
 
 If you want to add a new tutorial/example, treat this as the bar:
diff --git a/spore.toml b/spore.toml
index cc23f3f..d3bf6ee 100644
--- a/spore.toml
+++ b/spore.toml
@@ -4,6 +4,12 @@ version = "0.1.0"
 type = "platform"
 spore-version = ">=0.1.0"
 
+[platform]
+contract-module = "platform_contract"
+startup-contract = "main"
+adapter-function = "main_for_host"
+handles = ["Console", "FileRead", "FileWrite", "Env", "Spawn"]
+
 [capabilities]
 allow = ["Compute"]
 
diff --git a/src/host.sp b/src/host.sp
index 389a630..67191fd 100644
--- a/src/host.sp
+++ b/src/host.sp
@@ -1,5 +1,6 @@
-/// Platform startup adapter.
-/// This is where the platform sets up effect handlers before calling the application startup function.
+/// Compatibility startup adapter.
+/// Keep this entry in sync with `platform_contract.sp` until the compiler reads
+/// `[platform].contract-module` directly.
 pub fn main_for_host(app_main: () -> ()) -> () {
     app_main()
     return
diff --git a/src/platform_contract.sp b/src/platform_contract.sp
new file mode 100644
index 0000000..7c99ca9
--- /dev/null
+++ b/src/platform_contract.sp
@@ -0,0 +1,13 @@
+/// Platform contract module for `basic-cli`.
+/// Applications targeting this Platform must implement the same `main`
+/// signature in their entry module. Any `spec` items attached here will stack
+/// with the application's own `main` spec and both must hold.
+pub fn main() -> () {
+    ?platform_startup_contract
+}
+
+/// Platform-owned startup adapter.
+pub fn main_for_host(app_main: () -> ()) -> () {
+    app_main()
+    return
+}