feat: add initial runtime api

Author: Ma11hewThomas

docs/README.md

@@ -58,12 +58,21 @@
 - [setTestId](functions/setTestId.md)
 - [setTestIdsForReport](functions/setTestIdsForReport.md)
 
+## Runtime
+
+- [mergeTestData](functions/mergeTestData.md)
+
+## Classes
+
+- [CtrfRuntime](classes/CtrfRuntime.md)
+
 ## Enumerations
 
 - [SortOrder](enumerations/SortOrder.md)
 
 ## Interfaces
 
+- [TestContext](interfaces/TestContext.md)
 - [TestTree](interfaces/TestTree.md)
 - [TreeNode](interfaces/TreeNode.md)
 - [TreeOptions](interfaces/TreeOptions.md)
@@ -75,4 +84,7 @@
 
 ## Variables
 
+- [ctrf](variables/ctrf.md)
 - [CTRF\_NAMESPACE](variables/CTRF_NAMESPACE.md)
+- [ctrfRuntime](variables/ctrfRuntime.md)
+- [runtime](variables/runtime.md)

docs/classes/CtrfRuntime.md

@@ -0,0 +1,212 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / CtrfRuntime
+
+# Class: CtrfRuntime
+
+Defined in: [src/runtime/runtime.ts:48](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L48)
+
+AsyncLocalStorage-based test context manager.
+
+Provides isolated execution contexts for concurrent test scenarios using
+Node.js AsyncLocalStorage. Context data persists across async boundaries
+within the same logical test execution.
+
+## Example
+
+```typescript
+const runtime = new CtrfRuntime()
+runtime.startTestContext('test-name')
+runtime.addExtra('key', 'value')
+const context = runtime.endTestContext()
+```
+
+## Constructors
+
+### Constructor
+
+> **new CtrfRuntime**(): `CtrfRuntime`
+
+#### Returns
+
+`CtrfRuntime`
+
+## Methods
+
+### addExtra()
+
+> **addExtra**(`key`, `value`): `void`
+
+Defined in: [src/runtime/runtime.ts:108](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L108)
+
+Adds key-value pair to current context's extra object.
+
+Mutates the active context's extra property. Creates extra object if
+it doesn't exist. All values must be JSON-serializable.
+
+#### Parameters
+
+##### key
+
+`string`
+
+Property key for metadata
+
+##### value
+
+`unknown`
+
+JSON-serializable value
+
+#### Returns
+
+`void`
+
+#### Throws
+
+When no active AsyncLocalStorage context exists
+
+#### Example
+
+```typescript
+runtime.addExtra('priority', 'high')
+runtime.addExtra('tags', ['smoke', 'regression'])
+runtime.addExtra('metadata', { browser: 'chrome', viewport: '1920x1080' })
+```
+
+***
+
+### endTestContext()
+
+> **endTestContext**(): `undefined` \| [`TestContext`](../interfaces/TestContext.md)
+
+Defined in: [src/runtime/runtime.ts:139](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L139)
+
+Returns shallow copy of current context and exits AsyncLocalStorage scope.
+
+Context data is intended for enrichment only. Reporter implementations
+should merge only the `extra` field with their test data.
+
+#### Returns
+
+`undefined` \| [`TestContext`](../interfaces/TestContext.md)
+
+Shallow copy of TestContext or undefined if no active context
+
+#### Example
+
+```typescript
+const context = runtime.endTestContext()
+if (context) {
+  const enriched = { ...reporterData, extra: { ...context.extra, ...reporterData.extra } }
+}
+```
+
+***
+
+### getCurrentContext()
+
+> **getCurrentContext**(): `undefined` \| [`TestContext`](../interfaces/TestContext.md)
+
+Defined in: [src/runtime/runtime.ts:162](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L162)
+
+Returns current AsyncLocalStorage context without modifying it.
+
+#### Returns
+
+`undefined` \| [`TestContext`](../interfaces/TestContext.md)
+
+Current TestContext or undefined if no active context
+
+#### Example
+
+```typescript
+const current = runtime.getCurrentContext()
+if (current?.extra?.skipCleanup) {
+  // conditional logic based on context
+}
+```
+
+***
+
+### hasActiveContext()
+
+> **hasActiveContext**(): `boolean`
+
+Defined in: [src/runtime/runtime.ts:178](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L178)
+
+Checks for active AsyncLocalStorage context existence.
+
+#### Returns
+
+`boolean`
+
+true if context exists, false otherwise
+
+#### Example
+
+```typescript
+if (runtime.hasActiveContext()) {
+  runtime.addExtra('key', 'value')
+}
+```
+
+***
+
+### startTestContext()
+
+> **startTestContext**(`name`, `options?`): `void`
+
+Defined in: [src/runtime/runtime.ts:71](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L71)
+
+Creates new AsyncLocalStorage context and enters it synchronously.
+
+#### Parameters
+
+##### name
+
+`string`
+
+Test identifier string
+
+##### options?
+
+Optional context metadata
+
+###### filePath?
+
+`string`
+
+Absolute path to test file
+
+###### id?
+
+`string`
+
+Unique test identifier
+
+###### suite?
+
+`string`[]
+
+Suite hierarchy array
+
+#### Returns
+
+`void`
+
+#### Throws
+
+None - always succeeds
+
+#### Example
+
+```typescript
+runtime.startTestContext('user login test', {
+  suite: ['auth', 'integration'],
+  filePath: '/tests/auth.spec.ts',
+  id: 'declarative-uuid'
+})
+```

docs/functions/findTestById.md

@@ -8,7 +8,7 @@
 
 > **findTestById**(`report`, `testId`): `undefined` \| [`Test`](../interfaces/Test.md)
 
-Defined in: src/methods/test-id.ts:84
+Defined in: [src/methods/test-id.ts:91](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/methods/test-id.ts#L91)
 
 Finds a test by its ID in a report
 

docs/functions/generateTestIdFromProperties.md

@@ -8,7 +8,7 @@
 
 > **generateTestIdFromProperties**(`name`, `suite?`, `filePath?`): `string`
 
-Defined in: src/methods/test-id.ts:95
+Defined in: [src/methods/test-id.ts:102](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/methods/test-id.ts#L102)
 
 Generates a new test ID based on test properties (exposed utility)
 

docs/functions/getTestId.md

@@ -8,7 +8,7 @@
 
 > **getTestId**(`test`): `string`
 
-Defined in: src/methods/test-id.ts:61
+Defined in: [src/methods/test-id.ts:68](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/methods/test-id.ts#L68)
 
 Gets the test ID from a test object, generating one if it doesn't exist
 

docs/functions/mergeTestData.md

@@ -0,0 +1,52 @@
+[**CTRF v0.0.16**](../README.md)
+
+***
+
+[CTRF](../README.md) / mergeTestData
+
+# Function: mergeTestData()
+
+> **mergeTestData**\<`T`\>(`reporterTest`, `runtimeContext`): `T`
+
+Defined in: [src/runtime/runtime.ts:213](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/runtime/runtime.ts#L213)
+
+Merges reporter test data with runtime context metadata.
+
+Reporter data takes precedence. Runtime context enriches only the `extra`
+field. In case of key conflicts in `extra`, reporter values win.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Record`\<`string`, `any`\>
+
+## Parameters
+
+### reporterTest
+
+`T`
+
+Test data from framework reporter (source of truth)
+
+### runtimeContext
+
+Context from ctrfRuntime.endTestContext()
+
+`undefined` | [`TestContext`](../interfaces/TestContext.md)
+
+## Returns
+
+`T`
+
+Merged test object with enriched extra metadata
+
+## Example
+
+```typescript
+const merged = mergeTestData(
+  { name: 'test', status: 'passed', extra: { framework: 'data' } },
+  { name: 'test', extra: { runtime: 'metadata', framework: 'ignored' } }
+)
+// Result: { name: 'test', status: 'passed', extra: { runtime: 'metadata', framework: 'data' } }
+```

docs/functions/setTestId.md

@@ -8,7 +8,7 @@
 
 > **setTestId**(`test`): [`Test`](../interfaces/Test.md)
 
-Defined in: src/methods/test-id.ts:49
+Defined in: [src/methods/test-id.ts:56](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/methods/test-id.ts#L56)
 
 Sets a test ID for a test object based on its properties
 

docs/functions/setTestIdsForReport.md

@@ -8,7 +8,7 @@
 
 > **setTestIdsForReport**(`report`): [`Report`](../interfaces/Report.md)
 
-Defined in: src/methods/test-id.ts:73
+Defined in: [src/methods/test-id.ts:80](https://github.com/ctrf-io/ctrf-core-js/blob/main/src/methods/test-id.ts#L80)
 
 Sets test IDs for all tests in a report