@hasna/recordings 0.4.0 → 0.5.0

package/dist/hosted-v1-gdr9extc.js

@@ -0,0 +1,84 @@
+// @bun
+import {
+  ContractValidationError,
+  exports_external,
+  optionalWireMetadata,
+  recordingIDParser
+} from "./hosted-v1-aavn7ktb.js";
+
+// src/contracts/hosted-v1.ts
+function parser(schema) {
+  return {
+    parse(value) {
+      try {
+        return schema.parse(value);
+      } catch {
+        throw new ContractValidationError;
+      }
+    },
+    safeParse(value) {
+      try {
+        return { success: true, data: schema.parse(value) };
+      } catch {
+        return { success: false, error: { code: "invalid_contract" } };
+      }
+    }
+  };
+}
+var json = exports_external.lazy(() => exports_external.union([exports_external.null(), exports_external.boolean(), exports_external.number().finite(), exports_external.string(), exports_external.array(json), exports_external.record(json)]));
+var object = (shape) => exports_external.object(shape).catchall(json);
+var id = exports_external.string().refine((value) => recordingIDParser.safeParse(value).success);
+var timestamp = exports_external.string().datetime({ offset: true }).regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$(?![\s\S])/);
+var utcTimestamp = exports_external.string().datetime().regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$(?![\s\S])/);
+var title = exports_external.string().trim().min(1).max(200);
+var recordingInput = exports_external.object({ id, sessionId: id.optional(), title, transcript: exports_external.string().max(256000), durationMs: exports_external.number().finite().min(0).max(1800000) }).strict();
+var recording = object({ ...recordingInput.shape, createdAt: timestamp, updatedAt: timestamp, provenance: exports_external.record(json).optional() });
+var pasteInput = exports_external.object({
+  id,
+  recordingId: id.nullable().optional(),
+  text: exports_external.string().max(256000),
+  destinationAppId: exports_external.string().min(1).max(255).optional(),
+  destinationAppName: exports_external.string().min(1).max(200).optional(),
+  status: exports_external.enum(["attempted", "confirmed", "failed"]),
+  occurredAt: utcTimestamp.optional()
+}).strict();
+var receipt = object({
+  ...pasteInput.shape,
+  recordingId: id.nullable(),
+  occurredAt: timestamp,
+  createdAt: timestamp,
+  updatedAt: timestamp,
+  evidenceSource: exports_external.literal("client_reported")
+});
+var account = object({ id, displayName: exports_external.string(), email: exports_external.string(), createdAt: timestamp });
+var advertised = { wireVersion: exports_external.string().optional(), capabilities: exports_external.array(exports_external.string()).max(32).optional() };
+var compatible = (value) => {
+  try {
+    optionalWireMetadata(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var recordingInputParser = parser(recordingInput);
+var recordingParser = parser(recording);
+var pasteInputParser = parser(pasteInput);
+var pasteReceiptParser = parser(receipt);
+var pageOptionsParser = parser(exports_external.object({
+  limit: exports_external.number().int().min(1).max(100).optional(),
+  before: timestamp.optional(),
+  beforeId: id.optional()
+}).strict().refine((value) => value.beforeId === undefined === (value.before === undefined)));
+var bootstrapInputParser = parser(exports_external.object({}).strict());
+var renameInputParser = parser(exports_external.object({ title }).strict());
+var accountResponseParser = parser(object({ account, ...advertised }).refine(compatible));
+var versionResponseParser = parser(object({ name: exports_external.literal("recordings"), version: exports_external.string(), apiVersion: exports_external.literal("v1"), ...advertised }).refine(compatible));
+var healthResponseParser = parser(object({ status: exports_external.literal("ok") }));
+var readyResponseParser = parser(object({ status: exports_external.literal("ready") }));
+var recordingResponseParser = parser(object({ recording }));
+var recordingListParser = parser(object({ recordings: exports_external.array(recording).max(100) }));
+var pasteResponseParser = parser(object({ receipt }));
+var pasteListParser = parser(object({ receipts: exports_external.array(receipt).max(100) }));
+var pendingDeletionParser = parser(object({ audioCleanup: object({ state: exports_external.literal("pending") }) }));
+
+export { recordingInputParser, recordingParser, pasteInputParser, pasteReceiptParser, pageOptionsParser, bootstrapInputParser, renameInputParser, accountResponseParser, versionResponseParser, healthResponseParser, readyResponseParser, recordingResponseParser, recordingListParser, pasteResponseParser, pasteListParser, pendingDeletionParser };

package/dist/index.js

@@ -2081,7 +2081,7 @@ function setAgentFocus(idOrName, projectId, db) {
 // package.json
 var package_default = {
   name: "@hasna/recordings",
-  version: "0.4.0",
+  version: "0.5.0",
   type: "module",
   description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
   repository: {
@@ -2107,6 +2107,19 @@ var package_default = {
     "./sdk": {
       import: "./dist/sdk/index.js",
       types: "./dist/sdk/index.d.ts"
+    },
+    "./contracts/hosted-v1": {
+      import: "./dist/contracts/hosted-v1.js",
+      types: "./dist/contracts/hosted-v1.d.ts"
+    },
+    "./contracts/stream-v1": {
+      import: "./dist/contracts/stream-v1.js",
+      types: "./dist/contracts/stream-v1.d.ts"
+    },
+    "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+    "./hosted": {
+      import: "./dist/hosted/index.js",
+      types: "./dist/hosted/index.d.ts"
     }
   },
   engines: {
@@ -2118,17 +2131,17 @@ var package_default = {
     "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
     "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
     "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
-    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
     "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     migrate: "bun run scripts/migrate.ts",
     typecheck: "tsc --noEmit",
     "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-    test: "bun test",
+    test: "bun scripts/release-suite-gate.ts --all",
     "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
     "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
     "verify:ci-native": "bun scripts/ci-native-build.ts",
-    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "${RECORDINGS_TEST_TIMEOUT_MS:-120000}" $(bun scripts/ci-linux-suite.ts --gated)',
+    "test:gated": "bun scripts/release-suite-gate.ts",
     "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
     "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
     "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -2146,11 +2159,16 @@ var package_default = {
     "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
     prepublishOnly: "bun run typecheck && bun run release-suite-gate",
     "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+    "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
   },
   files: [
     "dist/",
+    "!dist/__tests__/",
     "scripts/",
+    "!scripts/test-recorder-fixtures.ts",
+    "!scripts/**/__pycache__/",
+    "!scripts/**/*.pyc",
     "Dockerfile.package",
     "bun.lock",
     "src/native/Recordings/App/",
@@ -2162,7 +2180,10 @@ var package_default = {
     "src/native/Recordings/build.sh",
     "packaging/macos/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "contracts/v1/fixtures.json",
+    "docs/wire-contracts.md",
+    "docs/hosted-sdk.md"
   ],
   dependencies: {
     "@aws-sdk/client-s3": "^3.1007.0",

package/dist/mcp/index.js

@@ -5048,7 +5048,7 @@ function setAgentFocus(idOrName, projectId, db) {
 // package.json
 var package_default = {
   name: "@hasna/recordings",
-  version: "0.4.0",
+  version: "0.5.0",
   type: "module",
   description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
   repository: {
@@ -5074,6 +5074,19 @@ var package_default = {
     "./sdk": {
       import: "./dist/sdk/index.js",
       types: "./dist/sdk/index.d.ts"
+    },
+    "./contracts/hosted-v1": {
+      import: "./dist/contracts/hosted-v1.js",
+      types: "./dist/contracts/hosted-v1.d.ts"
+    },
+    "./contracts/stream-v1": {
+      import: "./dist/contracts/stream-v1.js",
+      types: "./dist/contracts/stream-v1.d.ts"
+    },
+    "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+    "./hosted": {
+      import: "./dist/hosted/index.js",
+      types: "./dist/hosted/index.d.ts"
     }
   },
   engines: {
@@ -5085,17 +5098,17 @@ var package_default = {
     "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
     "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
     "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
-    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
     "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     migrate: "bun run scripts/migrate.ts",
     typecheck: "tsc --noEmit",
     "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-    test: "bun test",
+    test: "bun scripts/release-suite-gate.ts --all",
     "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
     "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
     "verify:ci-native": "bun scripts/ci-native-build.ts",
-    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "${RECORDINGS_TEST_TIMEOUT_MS:-120000}" $(bun scripts/ci-linux-suite.ts --gated)',
+    "test:gated": "bun scripts/release-suite-gate.ts",
     "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
     "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
     "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -5113,11 +5126,16 @@ var package_default = {
     "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
     prepublishOnly: "bun run typecheck && bun run release-suite-gate",
     "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+    "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
   },
   files: [
     "dist/",
+    "!dist/__tests__/",
     "scripts/",
+    "!scripts/test-recorder-fixtures.ts",
+    "!scripts/**/__pycache__/",
+    "!scripts/**/*.pyc",
     "Dockerfile.package",
     "bun.lock",
     "src/native/Recordings/App/",
@@ -5129,7 +5147,10 @@ var package_default = {
     "src/native/Recordings/build.sh",
     "packaging/macos/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "contracts/v1/fixtures.json",
+    "docs/wire-contracts.md",
+    "docs/hosted-sdk.md"
   ],
   dependencies: {
     "@aws-sdk/client-s3": "^3.1007.0",

package/dist/server/index.js

@@ -21,7 +21,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/recordings",
-    version: "0.4.0",
+    version: "0.5.0",
     type: "module",
     description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
     repository: {
@@ -47,6 +47,19 @@ var init_package = __esm(() => {
       "./sdk": {
         import: "./dist/sdk/index.js",
         types: "./dist/sdk/index.d.ts"
+      },
+      "./contracts/hosted-v1": {
+        import: "./dist/contracts/hosted-v1.js",
+        types: "./dist/contracts/hosted-v1.d.ts"
+      },
+      "./contracts/stream-v1": {
+        import: "./dist/contracts/stream-v1.js",
+        types: "./dist/contracts/stream-v1.d.ts"
+      },
+      "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+      "./hosted": {
+        import: "./dist/hosted/index.js",
+        types: "./dist/hosted/index.d.ts"
       }
     },
     engines: {
@@ -58,17 +71,17 @@ var init_package = __esm(() => {
       "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
       "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
       "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
-      "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
+      "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
       "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
       "generate:sdk": "bun run scripts/generate-sdk.ts",
       migrate: "bun run scripts/migrate.ts",
       typecheck: "tsc --noEmit",
       "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-      test: "bun test",
+      test: "bun scripts/release-suite-gate.ts --all",
       "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
       "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
       "verify:ci-native": "bun scripts/ci-native-build.ts",
-      "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "${RECORDINGS_TEST_TIMEOUT_MS:-120000}" $(bun scripts/ci-linux-suite.ts --gated)',
+      "test:gated": "bun scripts/release-suite-gate.ts",
       "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
       "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
       "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -86,11 +99,16 @@ var init_package = __esm(() => {
       "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
       prepublishOnly: "bun run typecheck && bun run release-suite-gate",
       "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-      "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+      "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+      "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
     },
     files: [
       "dist/",
+      "!dist/__tests__/",
       "scripts/",
+      "!scripts/test-recorder-fixtures.ts",
+      "!scripts/**/__pycache__/",
+      "!scripts/**/*.pyc",
       "Dockerfile.package",
       "bun.lock",
       "src/native/Recordings/App/",
@@ -102,7 +120,10 @@ var init_package = __esm(() => {
       "src/native/Recordings/build.sh",
       "packaging/macos/",
       "README.md",
-      "LICENSE"
+      "LICENSE",
+      "contracts/v1/fixtures.json",
+      "docs/wire-contracts.md",
+      "docs/hosted-sdk.md"
     ],
     dependencies: {
       "@aws-sdk/client-s3": "^3.1007.0",

package/dist/storage.js

@@ -1013,7 +1013,7 @@ function setAgentFocus(idOrName, projectId, db) {
 // package.json
 var package_default = {
   name: "@hasna/recordings",
-  version: "0.4.0",
+  version: "0.5.0",
   type: "module",
   description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
   repository: {
@@ -1039,6 +1039,19 @@ var package_default = {
     "./sdk": {
       import: "./dist/sdk/index.js",
       types: "./dist/sdk/index.d.ts"
+    },
+    "./contracts/hosted-v1": {
+      import: "./dist/contracts/hosted-v1.js",
+      types: "./dist/contracts/hosted-v1.d.ts"
+    },
+    "./contracts/stream-v1": {
+      import: "./dist/contracts/stream-v1.js",
+      types: "./dist/contracts/stream-v1.d.ts"
+    },
+    "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+    "./hosted": {
+      import: "./dist/hosted/index.js",
+      types: "./dist/hosted/index.d.ts"
     }
   },
   engines: {
@@ -1050,17 +1063,17 @@ var package_default = {
     "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
     "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
     "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
-    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
     "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     migrate: "bun run scripts/migrate.ts",
     typecheck: "tsc --noEmit",
     "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-    test: "bun test",
+    test: "bun scripts/release-suite-gate.ts --all",
     "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
     "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
     "verify:ci-native": "bun scripts/ci-native-build.ts",
-    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "${RECORDINGS_TEST_TIMEOUT_MS:-120000}" $(bun scripts/ci-linux-suite.ts --gated)',
+    "test:gated": "bun scripts/release-suite-gate.ts",
     "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
     "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
     "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -1078,11 +1091,16 @@ var package_default = {
     "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
     prepublishOnly: "bun run typecheck && bun run release-suite-gate",
     "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+    "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
   },
   files: [
     "dist/",
+    "!dist/__tests__/",
     "scripts/",
+    "!scripts/test-recorder-fixtures.ts",
+    "!scripts/**/__pycache__/",
+    "!scripts/**/*.pyc",
     "Dockerfile.package",
     "bun.lock",
     "src/native/Recordings/App/",
@@ -1094,7 +1112,10 @@ var package_default = {
     "src/native/Recordings/build.sh",
     "packaging/macos/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "contracts/v1/fixtures.json",
+    "docs/wire-contracts.md",
+    "docs/hosted-sdk.md"
   ],
   dependencies: {
     "@aws-sdk/client-s3": "^3.1007.0",

package/docs/hosted-sdk.md

@@ -0,0 +1,71 @@
+# Hosted SDK
+
+`@hasna/recordings/hosted` provides `HostedRecordingsClient` for hosted recording
+metadata, account and paste-history operations. The existing `./sdk` retains its
+separate legacy API. This additive client neither translates legacy fields nor
+records audio, opens a login browser, manages credentials or starts a speech
+provider. Bun is the tested runtime; browser compatibility is not claimed.
+
+```ts
+import { HostedRecordingsClient, recordingCursor } from "@hasna/recordings/hosted";
+
+const client = new HostedRecordingsClient({
+  apiBase: configuration.completeV1Base,
+  credentialProvider: ({ apiBase, signal }) => session.accessTokenFor(apiBase, signal),
+});
+const { recordings } = await client.listRecordings({ limit: 25 });
+if (recordings.length === 25) {
+  const next = await client.listRecordings({ limit: 25, ...recordingCursor(recordings.at(-1)!) });
+}
+```
+
+The caller supplies a complete API base ending in `/v1`, including any prefix.
+Remote bases require HTTPS; HTTP requires an explicit exact loopback address.
+The client has no default endpoint or ambient environment, disk or Keychain
+credential lookup. Public `health()` and `version()` never request credentials;
+all other methods request a fresh caller-supplied Bearer credential. Injected
+`fetch` is trusted and must honor manual redirects and AbortSignal. No request
+follows a redirect, sends cookies or retries automatically.
+
+`bootstrap()` sends an empty object; the server derives account/profile authority
+from the authenticated session. `account()` reads that account and `ready()`
+checks authenticated readiness. The caller owns OAuth, refresh and credential
+storage. `logout()` revokes the current server session family; the caller must
+also clear its stored credentials.
+
+`listRecordings`, `getRecording`, `saveRecording` and `renameRecording` use
+camelCase values: `id`, optional `sessionId`, `title`, `transcript`, and
+`durationMs`. Duration is milliseconds. `deleteRecording` returns
+`{state:'pending'}` for accepted cleanup or `{state:'removed'}` for completed
+deletion. Pending is not proof that audio has been purged. Repeat explicitly;
+reads may return the `recording_deleted` error after a permanent tombstone.
+
+`listPasteReceipts`, `savePasteReceipt`, `deletePasteReceipt` and
+`clearPasteHistory` use the hosted paste contract. An input `occurredAt` must be
+UTC ending in `Z`; omit it for server time. `client_reported` receipt evidence
+does not mean the server observed the target. Empty text remains valid when
+retention is disabled. Recordings and receipts can contain private text; callers
+should avoid logging responses.
+
+Both lists require `before` and `beforeId` together or neither. `recordingCursor`
+selects the last row's `createdAt` and ID; `pasteCursor` selects its `occurredAt`
+and ID. There is no inferred total or automatic pagination. A full page can be
+the last page. Inputs are validated before credentials or fetch; future JSON
+response fields are preserved. Advertised metadata must include a compatible
+version and all required capabilities; entirely absent metadata remains legacy
+compatible. This is stricter than an older hosted adapter that accepted empty
+capability advertisements.
+
+The default 20-second deadline includes credential acquisition and the entire
+response body. Caller cancellation has the same scope. Encoded JSON requests
+are limited to 1 MiB before credentials are requested. Responses are limited to
+4 MiB of decoded bytes by default, configurable from 1 KiB to 32 MiB; compressed
+wire Content-Length is not compared with decoded size. The transport bounds its
+growing buffer, not total process memory. Error bodies are cancelled unread.
+
+`RecordingsSDKError` contains a fixed code/message and optional HTTP status and
+validated UUID request ID. It retains no body, endpoint, token, server message or
+original cause. A timed-out mutation may already have committed: reconcile using
+the known recording or receipt ID instead of blindly retrying. This JSON client
+does not implement audio upload/download, WebSocket sessions, native app control,
+tenant storage, usage admission or provider execution.

package/docs/wire-contracts.md

@@ -0,0 +1,24 @@
+# Hosted recording wire contracts
+
+The additive `@hasna/recordings/contracts/hosted-v1` and `@hasna/recordings/contracts/stream-v1` exports describe hosted recording metadata and PCM streaming. They perform no I/O, choose no endpoint, read no credentials and implement no provider or storage backend. Existing `./sdk`, CLI, MCP, serve, projects and native provider interfaces keep their existing behavior. The hosted camelCase API is distinct from the legacy SDK's snake_case API. Qualified timestamps require seconds; numeric offsets require a colon and valid hour/minute ranges.
+
+```ts
+import { recordingInputParser } from "@hasna/recordings/contracts/hosted-v1";
+import { streamEventParser } from "@hasna/recordings/contracts/stream-v1";
+
+const request = recordingInputParser.parse(input);
+const event = streamEventParser.safeParse(decodedEvent);
+if (!event.success) handleInvalidContract(event.error.code);
+```
+
+Every parser exposes an explicit `ContractParser<T>` interface with plain DTOs. `parse` throws a fixed `ContractValidationError`; `safeParse` returns `{success: true, data}` or `{success: false, error: {code: "invalid_contract"}}`. Neither error retains rejected data, schema-library internals or a cause. Consumers using different validation libraries can use these interfaces without exchanging Zod types.
+
+Inputs reject unknown fields. Recording input has a UUID, title, transcript and duration in milliseconds; caller input cannot supply trusted provenance. Titles are trimmed. Paste input uses UTC timestamps ending in `Z`; output timestamps may have offsets. A paste receipt's `client_reported` evidence does not mean the server observed the target. Pagination requires `before` and `beforeId` together, or neither; either cursor component alone is invalid. Responses preserve extra JSON fields, including nested fields, while still checking known fields.
+
+Hosted wire version `1.0` is independent of package and local-control versions. Metadata may be entirely absent for legacy v1. Once advertised, version and capabilities must both be present: major `1`, bounded minor, unique valid capability names, and all four required capabilities. Future compatible minors and additional capabilities are accepted. No incompatible advertisement downgrades to legacy mode. Bootstrap and version response parsers enforce these rules too. This intentionally tightens the previous hosted SDK's permissive metadata parsing to match service/native negotiation; it does not modify the legacy public SDK.
+
+Streaming controls are strict. `parseStreamControlJSON` also enforces the existing 20,000-byte UTF-8 control-message ceiling. `pcmFrameParser` accepts only nonempty even-length PCM16 frames, from 2 through 24,000 bytes, without copying or converting them. The format is 24 kHz mono signed little-endian PCM16. Stream event parsers validate known event types, bounds, final capture identity and complete advertised metadata. New fields are allowed; unknown event types are rejected. Legacy final events may omit segments/provenance/recordingId, and legacy ready events may omit metadata/window fields.
+
+These are value contracts, not a session state machine. The consumer must bind events to its current capture, require ready before sending, enforce sequence ordering, cumulative/buffer/deadline limits, require input finish before final delivery, validate renewal expiry against its clock, and require ready metadata when bootstrap advertised it. `acceptsAudioAcknowledgement` is a pure check against the consumer's sent and acknowledged byte counts; it does not update those counts. The consumer owns consent, authorization, cancellation and error display. Error-event messages are untrusted data and must not be logged as validation diagnostics.
+
+Fictional positive and negative interoperability vectors are exported as `@hasna/recordings/contracts/fixtures/v1`. They freeze current input/output differences explicitly. Contract additions do not repoint or replace any legacy API. A subsequent reviewed package release and consumer adoption are required; introducing these modules does not publish them or change a deployed service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/recordings",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Speech-to-text recording tool with MCP and CLI — records, transcribes, and optionally enhances text using AI",
   "repository": {
@@ -26,6 +26,19 @@
     "./sdk": {
       "import": "./dist/sdk/index.js",
       "types": "./dist/sdk/index.d.ts"
+    },
+    "./contracts/hosted-v1": {
+      "import": "./dist/contracts/hosted-v1.js",
+      "types": "./dist/contracts/hosted-v1.d.ts"
+    },
+    "./contracts/stream-v1": {
+      "import": "./dist/contracts/stream-v1.js",
+      "types": "./dist/contracts/stream-v1.d.ts"
+    },
+    "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+    "./hosted": {
+      "import": "./dist/hosted/index.js",
+      "types": "./dist/hosted/index.d.ts"
     }
   },
   "engines": {
@@ -37,17 +50,17 @@
     "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
     "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
     "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
-    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
     "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     "migrate": "bun run scripts/migrate.ts",
     "typecheck": "tsc --noEmit",
     "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-    "test": "bun test",
+    "test": "bun scripts/release-suite-gate.ts --all",
     "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
     "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
     "verify:ci-native": "bun scripts/ci-native-build.ts",
-    "test:gated": "bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS=\"${RECORDINGS_TEST_TIMEOUT_MS:-120000}\" bun test --timeout \"${RECORDINGS_TEST_TIMEOUT_MS:-120000}\" $(bun scripts/ci-linux-suite.ts --gated)",
+    "test:gated": "bun scripts/release-suite-gate.ts",
     "test:vacuity-battery": "bun scripts/vacuity-manifest-gen.ts > \"${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv\" && bun scripts/vacuity-mutation-battery.ts \"${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv\"",
     "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
     "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -65,11 +78,16 @@
     "prepack:platform-gate": "bash -c 'if [ \"$(uname -s)\" = Darwin ]; then bun run build:native-fs-guard; else echo \"WARN: native fs-guard build skipped on $(uname -s) — dry-run/CI pack; publish recordings from macOS\"; fi'",
     "prepublishOnly": "bun run typecheck && bun run release-suite-gate",
     "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+    "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
   },
   "files": [
     "dist/",
+    "!dist/__tests__/",
     "scripts/",
+    "!scripts/test-recorder-fixtures.ts",
+    "!scripts/**/__pycache__/",
+    "!scripts/**/*.pyc",
     "Dockerfile.package",
     "bun.lock",
     "src/native/Recordings/App/",
@@ -81,7 +99,10 @@
     "src/native/Recordings/build.sh",
     "packaging/macos/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "contracts/v1/fixtures.json",
+    "docs/wire-contracts.md",
+    "docs/hosted-sdk.md"
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1007.0",