docs(iteration): freeze sdk v1 contract fixtures

2026-08-05 16:36:01 +08:00
parent 9fb8cd1598
commit 486280bec0
13 changed files with 1805 additions and 828 deletions
@@ -0,0 +1,66 @@
+{
+  "contract": "lineup-miniapp-sdk-v1-golden-1",
+  "description": "03.sdk_and_coreapp frozen runtime contract cases. These cases express the required observable result; they do not grant MiniApps access to Runtime internals.",
+  "cases": [
+    {
+      "id": "bundled-manifest-requires-surface",
+      "input": { "manifest": { "kind": "bundled", "host": { "surface_required": true } } },
+      "expected": { "accepted": true }
+    },
+    {
+      "id": "bundled-manifest-without-surface-rejected",
+      "input": { "manifest": { "kind": "bundled", "host": { "surface_required": false } } },
+      "expected": { "accepted": false, "code": "manifest_denied" }
+    },
+    {
+      "id": "interactive-without-app-context-goes-to-main-im",
+      "input": { "tool": { "handling": "interactive" } },
+      "expected": { "app_session_id": null, "creates_business_instance": false, "enters_miniapp_inbox": false }
+    },
+    {
+      "id": "interactive-with-verified-closed-app-session-keeps-history-context",
+      "input": { "tool": { "handling": "interactive" }, "app_session_context": { "app_session_id": "session-whiteboard-1", "state": "ended", "same_agent": true, "same_conversation": true } },
+      "expected": { "app_session_id": "session-whiteboard-1", "creates_business_instance": false, "revives_instance": false }
+    },
+    {
+      "id": "interactive-with-cross-conversation-app-session-rejected",
+      "input": { "tool": { "handling": "interactive" }, "app_session_context": { "app_session_id": "session-other", "state": "active", "same_agent": true, "same_conversation": false } },
+      "expected": { "accepted": false, "code": "app_session_context_invalid", "creates_interaction": false }
+    },
+    {
+      "id": "answerable-interaction-uses-default-expiry",
+      "input": { "request": { "kind": "confirm" } },
+      "expected": { "expires_in_ms": 900000 }
+    },
+    {
+      "id": "answerable-interaction-expiry-boundary",
+      "input": { "request": { "kind": "input", "expires_in_ms": 60000 } },
+      "expected": { "accepted": true, "expires_in_ms": 60000 }
+    },
+    {
+      "id": "notice-does-not-accept-expiry",
+      "input": { "request": { "kind": "notice", "expires_in_ms": 60000 } },
+      "expected": { "accepted": false, "code": "interaction_request_invalid" }
+    },
+    {
+      "id": "dismiss-is-idempotent-and-addressed-by-call-id",
+      "input": { "dismiss": { "control_id": "dismiss-1", "call_id": "interactive-call-1" }, "interaction": { "status": "pending", "same_agent": true, "same_conversation": true } },
+      "expected": { "status": "cancelled", "tool_outbox_count": 1, "replay_outbox_count": 0 }
+    },
+    {
+      "id": "accepted-app-close-cancels-running-tool",
+      "input": { "close": { "accepted": true }, "tool": { "status": "running", "instance_id": "task-dashboard-1" } },
+      "expected": { "tool_status": "cancelled", "cancel_reason": "app_closed", "tool_outbox_count": 1, "close_surface": true, "stop_instance": true }
+    },
+    {
+      "id": "accepted-app-close-preserves-submitted-result",
+      "input": { "close": { "accepted": true }, "tool": { "status": "submitted", "instance_id": "whiteboard-1" } },
+      "expected": { "tool_status": "submitted", "continue_existing_outbox": true, "close_surface": true, "stop_instance": true }
+    },
+    {
+      "id": "tool-complete-does-not-close-bundled-app",
+      "input": { "tool": { "status": "completed", "app_kind": "bundled" } },
+      "expected": { "close_surface": false, "stop_instance": false, "end_app_session": false }
+    }
+  ]
+}
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import fixture from "@/runtime/app-management/golden/miniapp-sdk-v1.json";
+
+type GoldenCase = Readonly<{
+  id: string;
+  input: Readonly<Record<string, unknown>>;
+  expected: Readonly<Record<string, unknown>>;
+}>;
+
+const cases = fixture.cases as readonly GoldenCase[];
+
+describe("MiniApp SDK v1 frozen golden contract", () => {
+  it("uses the versioned 03.sdk_and_coreapp fixture and stable case ordering", () => {
+    expect(fixture.contract).toBe("lineup-miniapp-sdk-v1-golden-1");
+    expect(cases.map(entry => entry.id)).toEqual([
+      "bundled-manifest-requires-surface",
+      "bundled-manifest-without-surface-rejected",
+      "interactive-without-app-context-goes-to-main-im",
+      "interactive-with-verified-closed-app-session-keeps-history-context",
+      "interactive-with-cross-conversation-app-session-rejected",
+      "answerable-interaction-uses-default-expiry",
+      "answerable-interaction-expiry-boundary",
+      "notice-does-not-accept-expiry",
+      "dismiss-is-idempotent-and-addressed-by-call-id",
+      "accepted-app-close-cancels-running-tool",
+      "accepted-app-close-preserves-submitted-result",
+      "tool-complete-does-not-close-bundled-app",
+    ]);
+  });
+
+  it("contains only cases with an input and observable expected result", () => {
+    for (const entry of cases) {
+      expect(entry.id).toMatch(/^[a-z][a-z0-9-]+$/);
+      expect(Object.keys(entry.input).length).toBeGreaterThan(0);
+      expect(Object.keys(entry.expected).length).toBeGreaterThan(0);
+    }
+  });
+});